Skip to main content

​
Workflow DSL

Fabriqa workflows are folder-based definitions that tell the product how a workflow should plan, execute, structure, and persist its artifacts. The Workflow DSL follows one rule: prompts drive the flow, and the DSL defines the contracts.
Agents still decide when to plan, create follow-up work, replan, or complete work. The DSL gives Fabriqa and your agents a shared model for artifacts, lifecycles, document semantics, and workflow shell UI.

​
What you can define

Workflow envelope

Define workflow metadata, phases, agents, connector subscriptions, relations, and sidebar defaults.

Artifact schemas

Define artifact shape, lifecycle, and document semantics.

Agents and prompts

Define SAF files, agent kinds, prompt responsibilities, coding tool access, and connector configs.

AI-DLC example

See a complete built-in workflow modeled with this DSL.

Workflow glossary

Look up the core terms used across workflow authoring, artifact schemas, and AI-DLC.

​
Core design principles

  • Keep workflow.yaml orchestration-focused.
  • Keep workflow shell UI in workflow.yaml.
  • Treat dashboard and root artifact viewer as product-defined surfaces, not authored workflow views.
  • Keep the workflow UI to three product-defined surfaces: sidebar, dashboard, and root artifact viewer.
  • Keep artifact-local meaning in artifact schema files.
  • Prefer markdown sections for the main document body.
  • Let Fabriqa infer metadata automatically from non-section fields and built-in system fields.
  • Treat the document body as a read-only markdown page, not a field inspector.
  • Keep contextual lists such as hierarchy, relations, linked chats, and activity out of the document body.
  • Do not add artifact-local UI config in V1.
  • Use lifecycle definitions to describe artifact states, not the whole workflow sequence.
  • Keep prompts responsible for sequencing and artifact behavior.
definitions/<workflow-id>/
  workflow.yaml
  agents/
    <agent>.saf
  prompts/
    <agent>.md
  schemas/
    <artifact>.yaml
  connectors/
    <connector>.yaml
  templates/
    <artifact>.md.tmpl
Use this split consistently:
  • workflow.yaml owns orchestration and shared references.
  • schemas/*.yaml own artifact-local structure and lifecycle.
  • agents/*.saf and prompts/*.md own agent behavior.
  • connectors/*.yaml own connector mapping shape.
  • templates/*.md.tmpl usually belong to the file connector.

​
How to read this guide

1

Start with the workflow envelope

Read Workflow file to understand how phases, agents, connectors, relations, and workflow UI defaults fit together.
2

Design your artifacts

Read Artifact schemas to define artifact payload shape, document semantics, and lifecycle state.
3

Finish agents and connectors

Read Agents and connectors to define SAF files, prompt boundaries, export templates, and authoring rules.
4

Compare with a built-in workflow

Read AI-DLC workflow to see how a complete workflow is structured from the user’s perspective and from the DSL’s perspective.

​
Good fit for the Workflow DSL

Use the Workflow DSL when you want:
  • a planning workflow with explicit artifacts
  • an execution workflow with structured evidence
  • a multi-agent process with clear handoffs
  • a document-first artifact viewer instead of flat forms
  • reusable workflow definitions across teams or workspaces

Workflow file

Continue into the orchestration envelope and shared workflow references.

Artifact schemas

Continue into the artifact model, document sections, and lifecycles.

Agents and connectors

Finish the workflow with SAF files, prompts, export templates, and authoring rules.

Workflow glossary

Keep a shared vocabulary open while you read the reference.