Workflow versioning
A Workflow Template is immutable and versioned. Its id is stable, but its behavior never changes in place: editing a template publishes a new version. Each Run pins the exact version it executed, so the Artifact it produced stays reproducible against the precise definition that made it.
Immutable versions, stable id
A template has a stable id (its slug) that identifies the job — for example generate-research-report — and one or more immutable versions under that id. You never mutate a published version. A change to the prompt, the model pin, the step graph, the gates, or the budget policy is published as a new version; the old version is kept exactly as it was.
generate-research-report ← stable id (slug)
├── 2026.05.29 (immutable)
├── 2026.06.10 (immutable) ← canonical (the live default)
└── 2026.06.18 (immutable)Choosing the live version
Because the id carries many versions, a movable pointer selects which one operators get by default — the canonical version. Promotion moves the pointer to a newer version; it never edits a version. Older versions remain resolvable so historical runs stay reproducible, and a workflow may keep opt-in alternates or operator-only shadow versions alongside its canonical one.
Drafts and publishing
A template can be saved as a draft while it is still incomplete — a half-written prompt or a reference that doesn’t resolve yet is fine to keep around. Publishing it — promoting it up the visibility ladder to internal or public (see Publishing & visibility) — is the gate: the definition is validated first, so a template with unresolved references, a forward reference to a later step, or a missing sub-workflow cannot be published — and therefore cannot be run. Publishing a valid template is what mints the immutable version described above.
When to bump a version vs. spawn a sibling
Bump a version when it’s the same job — same input and output contract, same intent — served by a different model decision. Spawn a separate workflow when the output identity changes: a research-assisted variant is a new template, not a new version of an existing one.
| Bump | When | Example |
|---|---|---|
| Patch | Same model family, newer dated snapshot, no behavioral drift | gpt-image-2-2026-04-21 → gpt-image-2-2026-06-15 |
| Minor | Model swap in the same quality/cost class with a documented behavior difference | swap one step’s model within the same tier |
| Major | Material change to style, cost, or output shape | replace the image model with a different one |
Runs pin the version
When a run starts, it resolves the template into a Workflow Specification — the version’s definition with this run’s inputs slotted in — and records the version and a hash of that frozen specification (specVersionHash). Editing or promoting the template later cannot change what an in-flight or historical run means: each run is anchored to the exact definition it executed.
run
├── workflowId generate-research-report
├── version 2026.06.10 (pinned at run start)
├── specVersionHash sha256:… (the frozen Specification)
├── resolved models anthropic/claude-opus-4-8, …
└── artifact → traces back to this exact versionImmutable versions make runs reproducible and auditable, keep a template edit from silently changing the meaning of past runs, and let a published artifact carry verifiable provenance — the exact version and the models that produced it — rather than a hand-maintained label.
On the word “manifest”
A manifest is the serialized, content-addressed form of a single immutable template version — the frozen bundle (input contract, pipeline, per-step policy, output contract) identified by a hash. It is not a separate concept layered on top of templates; it is what an immutable version is when written down for storage, comparison, or provenance. The marketing site surfaces a version’s manifest as the public record of what produced an artifact.
Related concepts
- Workflow templates — the versioned definitions this page governs.
- Workflow specifications — the per-run frozen form a run pins.
- Runs — pin the version and specification they executed.
- Artifacts — trace back to the exact template version that produced them.