Workflow Primitives
A workflow is defined by three distinct objects at three layers of abstraction. A Workflow Schema declares the rules. A Workflow Template is a predesigned workflow that satisfies those rules. A Workflow Specification is one populated instance of a Template, produced during a single Run.
TL;DR
A Workflow Schema declares the rules. A Workflow Template is a predesigned workflow that satisfies those rules. A Workflow Specification is one populated instance of a Template, produced during a single Run, that production reads to build the artifact.
The Three Levels
Each level has a different definition, a different audience, and a different lifecycle. Most people interacting with Esy work at only one level.
Workflow Schema
The rules every Workflow Template must obey. Declares what fields a workflow has, what shape a gate takes, what types intake and output can be.
Declares
- •Required fields a Template must contain
- •Allowed types and shapes per field
- •Gate-unlock condition grammar
- •Sub-workflow reference rules
- •Versioning conventions
- •Validation rules for Template publication
Workflow Template
A specific predesigned workflow conforming to the Schema. The named, packaged thing an operator picks when starting work.
Declares
- •Stable id, version, artifact class
- •Intake schema for operator inputs
- •Runtime steps and gates
- •Provider routing per step
- •Budget policy
- •Output shape contract
Workflow Specification
A per-run populated instance of a Template. The deterministic blueprint production reads to build the artifact.
Declares
- •Operator inputs filled in
- •Intermediate artifacts linked
- •Synthesis decisions captured
- •Production-ready blueprint
- •Provenance pointers (Template, Schema, Run)
Each level satisfies the level above it.
Type System Analogy
The three-level pattern mirrors how programming language type systems work. If TypeScript is familiar:
Foundational Principles
The takeaways that produced this vocabulary. Carry them forward.
Every Workflow Run produces a Workflow Specification
Even trivial workflows. For a daily SERP snapshot, the Specification may be ten lines — essentially the validated inputs. For a visual essay, it is 500–1,500 lines. Complexity varies; the primitive is universal. Production always reads the Specification, never the raw inputs.
The three-level pattern is universal across workflow complexity
Deterministic ETL, LLM-assisted production, mixed agent/code, fully agentic synthesis — all use the same Schema → Template → Specification primitives. What runs inside each gate is implementation, not type.
LLM call ≠ agent loop ≠ workflow
Three concepts at three granularities. An LLM call is a single inference. An agent is LLM + tools + loop + memory + stop condition. A workflow is a typed graph that may contain zero, one, or many of either. A step is not agentic just because an LLM is invoked.
The primitive is "Workflow," not "Agentic Workflow"
Implementation properties belong on instances, not in type names. Whether a Template runs agents, deterministic code, or both is metadata on the Template, not part of the primitives that name all workflows.
Templates and Frameworks are distinct objects
A Template is a declarative spec the platform reads. A Framework is an agent-facing operating manual that complements a Template — patterns, heuristics, anti-patterns. They describe the same workflow but serve different audiences.
Each level has a different audience
Operators rarely see the Schema. Platform engineers rarely look at individual Specifications. Designing docs and tooling around the right audience per level avoids cognitive overload.
How This Shows Up in the Repo Today
You do not need to refactor anything right now. The current structure works while Claude Code is the runtime. The vocabulary is the bridge to the platform shape, not a demand to rewrite existing files.
client/docs/src/app/concepts/workflow-templates/orchestration/skills/visual-essay-invocation/SKILL.mdsrc/app/essays/*/SPEC.mdorchestration/agents/orchestrators/visual-essay-orchestrator.mdWorkflow Specification vs Artifact Specification
A note for readers of Artifact Specifications. Those docs describe the metadata panel displayed on published artifacts — title, sourceCount, authorship. That is artifact-level inspection data rendered on the published page. A Workflow Specification is a different object.
Two distinct concepts using similar words
Artifact Specification = the published artifact's inspectable metadata panel. Lives forever on the published page. Readers see it.
The Artifact Specification is a downstream projection of the Workflow Specification plus Run metadata — but they are not the same object.
Canonical Reference on docs.esy.com
The detailed reference for each primitive — fields, types, validation rules, examples — lives at docs.esy.com. This page is the foundational overview; those pages are the working reference.
“Schema declares the rules. Template is a predesigned workflow. Specification is one populated instance per run. Production reads the specification to build the artifact.”