# description
A workflow pipeline definition using Graphviz DOT syntax to orchestrate multi-stage AI tasks.

# $comment
A workflow is a directory containing a `WORKFLOW.md` file with YAML frontmatter and a Markdown
body. The pipeline is defined as a Graphviz DOT digraph in the first ```dot code block in the
body. Additional Markdown content provides human-readable documentation for the workflow.

Workflows are discovered from `.stencila/workflows/<name>/WORKFLOW.md`.
Each node in the DOT graph can reference an agent by name via the `agent` attribute; agents are
resolved from workspace `.stencila/agents/` and user-level `~/.config/stencila/agents/`.
Because workflows are typically shared (committed to a repository as part of a lab), while
agents may be personal (user-level agents can encapsulate individual model preferences and
provider configuration), this separation allows the same shared workflow to be executed with
different agent configurations by different users. Agent definitions provide defaults for
model, provider, system instructions, and tools, but explicit node attributes override them.

The DOT graph follows the Attractor specification: a strict subset of digraph syntax with typed
attributes for node handlers, edge routing, retry policies, and human-in-the-loop gates.

# properties.type.$comment
This is a special property analogous to JSON-LD's `@type` keyword.

# properties.id.$comment
This is a special property analogous to JSON-LD's `@id` keyword.

# properties.identifiers.description
Any kind of identifier for any kind of Thing.

# properties.identifiers.$comment
Some identifiers have specific properties e.g the `issn` property for
the `Periodical` type. These should be used in preference to this
property which is intended for identifiers that do not yet have a
specific property. Identifiers can be represented as strings, but
using a `PropertyValue` will usually be better because it allows
for `propertyID` (i.e. the type of identifier).

# properties.name.$comment
Must be lowercase kebab-case: 1-64 characters, only lowercase alphanumeric
and hyphens, no leading/trailing/consecutive hyphens. By convention, names
describe the workflow's purpose, e.g. `code-review`, `test-and-deploy`,
`plan-implement-validate`.

# properties.workType.description
The type of `CreativeWork` (e.g. article, book, software application).

# properties.doi.description
The work's Digital Object Identifier (https://doi.org/).

# properties.about.$comment
Consistent with https://schema.org/about, this property allows for
linking to one of more `Thing` nodes. This could for example include
a `Person` (e.g for a bibliography) or a `DefinedTerm` (e.g. for
subject areas the creative work relates to).

# properties.abstract.description
A short description that summarizes a `CreativeWork`.

# properties.provenance.description
A summary of the provenance of the content within the work.

# properties.contributors.description
A secondary contributor to the `CreativeWork`.

# properties.editors.$comment
Note that, consistent with schema.org, this property can only include
a `Person`, unlike `authors` and `maintainers` which can also include
`Organization`.

# properties.maintainers.$comment
A maintainer of a `Dataset`, `SoftwareApplication`, or other `CreativeWork`.
A maintainer is a `Person` or `Organization` that manages contributions to,
and/or publication of, some (typically complex) artifact. It is common for
distributions of software and data to be based on "upstream" sources.
When maintainer is applied to a specific version of something e.g. a particular
version or packaging of a Dataset, it is always possible that the upstream
source has a different maintainer. The `isBasedOn` property can be used to
indicate such relationships between datasets to make the different maintenance
roles clear. Similarly in the case of software, a package may have dedicated
maintainers working on integration into software distributions such as Ubuntu,
as well as upstream maintainers of the underlying work.

# properties.dateAccepted.$comment
This is not yet a schema.org property but the term is used
[in Dublin Core](http://purl.org/dc/terms/dateAccepted).

# properties.funders.description
People or organizations that funded the `CreativeWork`.

# properties.fundedBy.description
Grants that funded the `CreativeWork`; reverse of `fundedItems`.

# properties.fundedBy.$comment
This follows the proposal [here](https://github.com/schemaorg/schemaorg/issues/2258)
for a property that is the reverse of `fundedItems`.
It is an any because a `CreativeWork` may have been funded through more than
one `Grant`.

# properties.genre.description
Genre of the creative work, broadcast channel or group.

# properties.keywords.description
Keywords or tags used to describe this content. Multiple entries in a keywords list are typically delimited by commas.

# properties.isPartOf.description
An item or other CreativeWork that this CreativeWork is a part of.

# properties.licenses.description
License documents that applies to this content, typically indicated by URL, but may be a `CreativeWork` itself.

# properties.parts.description
Elements of the collection which can be a variety of different elements, such as Articles, Datatables, Tables and more.

# properties.bibliography.description
A bibliography of references which may be cited in the work.

# properties.bibliography.$comment
Unlike `references` which contains only the references that are actually
cited in the work, `bibliography` is a database of all available references
loaded from an external source file at compile time. It is ephemeral and
not persisted when the document is saved.

# properties.references.description
References to other creative works, such as another publication, web page, scholarly article, etc.

# properties.text.description
The textual content of this creative work.

# properties.repository.description
URL of the repository where the un-compiled, human readable source of the work is located.

# properties.path.description
The file system path of the source of the work.

# properties.path.$comment
Usually only used when the work is within a Git (or other version control) repository,
and then is usually relative to the repository root.

# properties.commit.description
The commit hash (or similar) of the source of the work.

# properties.commit.$comment
Only used when the work's source file is within a Git (or other version control) repository.

# properties.version.$comment
In this case `string` is listed as an alternative before `number` to
avoid semantic version numbers e.g. `1.0` being parsed, and subsequently
encoded, as `1` thereby resulting in loss of information.

# properties.whenToUse.description
Positive selection signals describing when this workflow should be used.

# properties.whenNotToUse.description
Negative selection signals describing when this workflow should not be used.

# properties.content.description
The content of the workflow (Markdown body containing the DOT pipeline and documentation).

# properties.content.$comment
When present, the Markdown body should contain at least one ```dot fenced code block
defining the pipeline digraph. Additional Markdown content serves as human-readable
documentation. The first ```dot code block is extracted as the pipeline definition during
decoding. For in-memory workflows, content may be omitted if the pipeline property is
set directly.

# properties.pipeline.description
The raw DOT source defining the pipeline digraph.

# properties.pipeline.$comment
Extracted from the first ```dot fenced code block in the content during decoding.
Can also be set directly for programmatic workflow construction. When encoding to
Markdown, the pipeline string is embedded as a ```dot code block in the content.

The DOT source must define a single `digraph` with exactly one start node
(shape=Mdiamond) and one exit node (shape=Msquare). Nodes use the `agent` attribute
to reference agent definitions by name, e.g. `implement [agent="code-engineer"]`.

# properties.goal.description
A fixed, predetermined high-level goal for the pipeline.

# properties.goal.$comment
Use only when the workflow has a stable objective that does not change between runs.
Exposed as `$goal` in node prompt templates and mirrored into the run context as
`graph.goal`. Maps to the `goal` graph-level attribute in the Attractor specification.
Most workflows expect the user to supply their own goal at run time; for those
workflows, use `goalHint` instead.

# properties.goalHint.description
Hint text displayed in user interfaces to guide the user to provide a specific goal.

# properties.goalHint.$comment
Most workflows should include this because most workflows expect the user to supply
their own objective at run time. The text is shown as a prompt or hint across user
interfaces (TUI, web, email, Slack, etc.) when the workflow is activated. The user's
response becomes `$goal` at runtime. This field is a UI hint only and is never
substituted into prompts directly.

# properties.overrides.description
CSS-like rules for per-node agent overrides across the pipeline.

# properties.overrides.$comment
The main mechanism for configuring agent behavior is through agent definitions
referenced via the `agent` attribute on each node. The overrides property provides
a supplementary mechanism for bulk per-node agent overrides by class or ID — useful
when you want to adjust model, provider, or other agent settings across many nodes
without modifying individual agent definitions or adding `agent.*` attributes to
every node. For example:

  overrides: |
    * { model: claude-sonnet-4-5 }
    .critical { reasoning_effort: high }
    #review { model: gpt-5.2; provider: openai }

Specificity order: `*` (universal) < `.class` < `#id`. Override values are
overridden by explicit `agent.*` node attributes. Maps to the `model_stylesheet`
graph-level attribute in the Attractor specification.

# properties.defaultMaxRetry.description
Global retry ceiling for nodes that omit max_retries.

# properties.defaultMaxRetry.$comment
Defaults to 50 per the Attractor specification. Maps to the `default_max_retry`
graph-level attribute.

# properties.retryTarget.description
Node ID to jump to if exit is reached with unsatisfied goal gates.

# properties.retryTarget.$comment
Maps to the `retry_target` graph-level attribute in the Attractor specification.

# properties.fallbackRetryTarget.description
Secondary jump target if retryTarget is missing or invalid.

# properties.fallbackRetryTarget.$comment
Maps to the `fallback_retry_target` graph-level attribute.

# properties.defaultFidelity.description
Default context fidelity mode for LLM sessions.

# properties.defaultFidelity.$comment
Controls how context values are compressed or summarized for LLM prompts.
Valid values: "full", "truncate", "compact", "summary:low", "summary:medium",
"summary:high". Maps to the `default_fidelity` graph-level attribute.