Workflow templates

Position in the model

Workflows on Esy are defined at three levels of abstraction. The Template is the middle layer — the named, packaged thing an operator picks when starting work. “Visual Essay,” “Generate Clip Art Asset,” “Generate Coloring Page” are all Templates. Each Template conforms to a Workflow Schema; each Run instantiates a Template into a Workflow Specification.

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

Composition

A workflow template is a versioned definition for how a particular kind of artifact gets produced. The id is stable; runtime behavior evolves through explicit versions and configuration snapshots captured on each run.

{
  "id": "generate-clip-art-asset",
  "name": "Generate Clip Art Asset",
  "artifactClass": "visual",
  "version": "2026.05.16",
  "schemaVersion": "workflow-schema-v1",
  "cadence": "On demand",
  "providers": {
    "image": "openai/gpt-image-2",
    "backgroundRemoval": "fal/birefnet-light"
  },
  "gates": ["prompt resolution", "provider execution", "background removal", "storage metadata", "HITL review"],
  "budgetPolicy": "Records estimated OpenAI image and fal.ai background-removal costs per run"
}

Anatomy

workflow template
   ├── intake schema
   ├── runtime steps
   ├── provider policy
   ├── quality gates
   ├── budget policy
   └── artifact schema

Fields

The definition is the program

A template is data-driven: its stored runtimeSteps are not documentation of what some server code does — they are what executes. A single generic engine reads a template’s steps and runs them (LLM call, image generation, tool call, agent loop, sub-workflow). There is no per-template, hand-written execution path: changing a template’s behavior means editing the template, not editing and redeploying server code. Two templates with different steps are the same engine running different data.

Resolving intake into prompts

A central promise of Esy is that operators don’t write prompts — they supply structured intake and context, and the template composes the real provider prompt behind the scenes. A step’s promptTemplate interpolates intake values by path ({intake.prompt}), so a short subject plus a few selections becomes the full engineered prompt the model actually sees. The operator never writes — or sees — that expansion.

Some composition needs more than substitution: a selection like a style key has to become a rich descriptor phrase. Templates express this declaratively with lookups — a named map from an intake value to a fragment, with a default — exposed to the prompt as {lookup.<name>}. This keeps the mapping as template data, not code, so authors can add or tune styles without touching the engine.

{
  "id": "render",
  "kind": "image",
  "model": "openai/gpt-image-2",
  "promptTemplate": "{intake.prompt}. Style: {lookup.styleDescriptor}, clip art, transparent background",
  "lookups": {
    "styleDescriptor": {
      "from": "intake.style",
      "map": {
        "flat": "flat vector, bold outlines, clean shapes, solid colors",
        "doodle": "hand-drawn doodle, sketchy lines, playful ink"
      },
      "default": "flat vector, bold outlines, clean shapes, solid colors"
    }
  }
}

Here an operator submits prompt: “a fox” and style: “doodle”; the engine resolves {lookup.styleDescriptor} to the doodle phrase and renders the complete prompt. An unknown style falls back to the declared default. Lookups are a generic engine primitive — any template can use them for any intake-to-prompt mapping, not just visual styles.

The database is the single source of truth

A template’s definition lives in the database and is authored, edited, and versioned through the API (POST / PATCH /v1/workflows) — the same path the Factory uses. The stored row is authoritative. Seed scripts are bootstrap-only: they may create initial rows, but they are not the source of truth and a row must never depend on re-running a script to stay correct. If a script and a row ever disagree, the row is what runs.

Publishing & visibility

A template’s visibility is the single control over where it is listed — a three-rung ladder, independent of any lifecycle status. Publishing is a deliberate promotion up the ladder, never a side effect of saving.

Because the rungs nest (anything public is also runnable in the app), demoting from public to internal unlists a template from the public catalog while keeping it runnable; demoting to draft pulls it everywhere. The public catalog shows only public, system-owned templates.

Publish guards

Promoting a template to a listed rung (internal or public) runs publish-time validation. Two guards keep a listed template honest:

Audience

Templates serve two audiences:

• Workflow designers — Author new Templates that conform to the Workflow Schema. Decide what gates a Template has, what providers route each step, and what artifact schema it produces. Authoring is admin-only: creating and editing templates is restricted to platform admins, and admin-published templates are system-owned.
• Operators — Pick a Template from a library and supply intake to start a Run. Operators do not author Templates; they instantiate them.

Frequency

Many. One per artifact class, versioned. Esy ships several Templates today (generate-clip-art-asset, visual-essay, generate-coloring-page-educational, and more) and new Templates are added as new artifact classes are introduced.

Related concepts

• Workflow schemas — the rules every Template must conform to.
• Workflow versioning — how a Template’s immutable versions are published, selected, and pinned by runs.
• Workflow specifications — per-run populated instances of a Template.
• Runs — durable execution records that instantiate Templates.
• Artifacts — the outputs produced by a Run, traced back to their Template version.