> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fabriqa.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Workflow DSL

> Design custom Fabriqa workflows with phases, agents, artifacts, inline lifecycles, and document-first artifact schemas.

# 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.

<Note>
  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.
</Note>

## What you can define

<CardGroup cols={2}>
  <Card title="Workflow envelope" icon="layout-list" href="/workflows/workflow-dsl-workflow-file">
    Define workflow metadata, phases, agents, connector subscriptions, relations, and sidebar defaults.
  </Card>

  <Card title="Artifact schemas" icon="scroll-text" href="/workflows/workflow-dsl-artifact-schemas">
    Define artifact shape, lifecycle, and document semantics.
  </Card>

  <Card title="Agents and prompts" icon="sparkles" href="/workflows/workflow-dsl-agents-and-connectors">
    Define SAF files, agent kinds, prompt responsibilities, coding tool access, and connector configs.
  </Card>

  <Card title="AI-DLC example" icon="zap" href="/workflows/ai-dlc">
    See a complete built-in workflow modeled with this DSL.
  </Card>

  <Card title="Workflow glossary" icon="book-open" href="/workflows/workflow-glossary">
    Look up the core terms used across workflow authoring, artifact schemas, and AI-DLC.
  </Card>
</CardGroup>

## 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.

## Recommended workflow folder layout

```text theme={null}
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

<Steps>
  <Step title="Start with the workflow envelope">
    Read [Workflow file](/workflows/workflow-dsl-workflow-file) to understand how phases, agents, connectors, relations, and workflow UI defaults fit together.
  </Step>

  <Step title="Design your artifacts">
    Read [Artifact schemas](/workflows/workflow-dsl-artifact-schemas) to define artifact payload shape, document semantics, and lifecycle state.
  </Step>

  <Step title="Finish agents and connectors">
    Read [Agents and connectors](/workflows/workflow-dsl-agents-and-connectors) to define SAF files, prompt boundaries, export templates, and authoring rules.
  </Step>

  <Step title="Compare with a built-in workflow">
    Read [AI-DLC workflow](/workflows/ai-dlc) to see how a complete workflow is structured from the user's perspective and from the DSL's perspective.
  </Step>
</Steps>

## 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

## Related pages

<CardGroup cols={2}>
  <Card title="Workflow file" icon="layout-list" href="/workflows/workflow-dsl-workflow-file">
    Continue into the orchestration envelope and shared workflow references.
  </Card>

  <Card title="Artifact schemas" icon="scroll-text" href="/workflows/workflow-dsl-artifact-schemas">
    Continue into the artifact model, document sections, and lifecycles.
  </Card>

  <Card title="Agents and connectors" icon="sparkles" href="/workflows/workflow-dsl-agents-and-connectors">
    Finish the workflow with SAF files, prompts, export templates, and authoring rules.
  </Card>

  <Card title="Workflow glossary" icon="book-open" href="/workflows/workflow-glossary">
    Keep a shared vocabulary open while you read the reference.
  </Card>
</CardGroup>