Concepts & Fundamentals

This document explains the core concepts behind Xema Workflows, including the DSL, compilation model, templates, and execution pipeline.

Table of Contents

1. What is a Workflow?
2. The DSL (Domain-Specific Language)
3. Workflow Structure
4. Compilation Model
5. Templates System
6. Phases & Artifacts
7. Execution Model

What is a Workflow?

A workflow is a declarative YAML specification that defines an automated process. In Xema, workflows:

• Are immutable — Once compiled, a workflow's execution is deterministic
• Are type-safe — Inputs, outputs, and actions are validated before execution
• Run on the Xema Workflow Runtime — A production-grade distributed workflow engine
• Support human collaboration — Approval gates, reviews, and manual interventions
• Integrate with external systems — GitHub, GitLab, Jira, Slack, webhooks, etc.

Example: High-Level Structure

1apiVersion: xema.dev/workflow/v1alpha1
2kind: Workflow
3metadata:
4  name: my-software-delivery
5  version: 1.0.0
6on:
7  workflow_dispatch:           # Manual trigger
8    inputs:
9      project_scope:
10        type: string
11        required: true
12jobs:
13  analyze:
14    uses: xema/agent        # Invoke an agent
15    with:
16      task: Analyze requirements
17  review:
18    needs: analyze             # Depends on analyze job
19    uses: xema/review       # Reviewer pool over `analyze`'s outputs

The DSL

The Xema Workflow DSL is a YAML-based, declarative language for defining automated processes.

Design Principles

1. Declarative — Describe what happens, not how
2. Strongly typed — All inputs, outputs, and parameters are typed
3. Fail-fast validation — Invalid workflows are rejected at compile time
4. Version-pinned — Actions and resources are referenced with explicit versions
5. Deterministic — Same (workflow version + inputs) always produces identical execution

API Version & Kind

All workflows must declare:

1apiVersion: xema.dev/workflow/v1alpha1
2kind: Workflow

This ensures compatibility with the workflow engine.

Top-Level Structure

1metadata:
2  name: workflow-name           # Unique within project
3  version: 1.0.0               # Semantic versioning
4description: Optional description
5
6on:                            # Trigger definitions
7  workflow_dispatch: { ... }   # Manual trigger
8  schedule: [ { ... } ]        # Cron schedule
9  webhook: [ { ... } ]         # External event
10  workflow_call: { ... }       # Called by other workflows
11
12concurrency:                   # Concurrency control
13  group: string                # Concurrency group
14  mode: allow | queue | cancel_in_progress | skip
15
16defaults:                      # Default settings
17  retry: { maxAttempts, backoffCoefficient, ... }
18  timeout: string              # e.g., "2h"
19
20permissions:                   # What workflows can access
21  repos: read | limited | write
22  kb: read | limited | write
23  backlog: read | limited | write
24  artifacts: read | limited | write
25  integrations: read | limited | write
26
27vars:                          # Static variables
28  key: value
29
30jobs:                          # Parallel/sequential jobs
31  job-key: { ... }

Workflow Structure

1. Metadata

Identifies and versions your workflow:

1metadata:
2  name: requirements-analysis
3  version: 2.1.0
4description: |
5  Automatically analyzes project requirements and generates
6  a requirements specification document.

2. Triggers (on:)

Defines when and how workflows are triggered. There are four trigger types:

a. Manual Trigger (workflow_dispatch)

Manually triggered by a user or API call:

1on:
2  workflow_dispatch:
3    inputs:
4      project_scope:
5        type: string
6        description: "Define the scope of the project"
7        required: true
8        format: multiline
9      include_budget:
10        type: boolean
11        description: "Include budget analysis?"
12        required: false
13        defaultValue: false
14      priority_level:
15        type: string
16        enum: [low, medium, high, critical]
17        required: true

Input Types: string, number, integer, boolean, object, array

b. Schedule Trigger (schedule)

Triggered on a cron schedule:

1on:
2  schedule:
3    - cron: "0 9 * * MON"    # Every Monday at 9 AM
4      inputs:
5        report_type: weekly
6    - cron: "0 0 1 * *"       # First day of month at midnight
7      inputs:
8        report_type: monthly

c. Webhook Trigger (webhook)

Triggered by external events (GitHub push, Jira issue created, etc.):

1on:
2  webhook:
3    - event: scm.push           # SCM push event
4      filters:
5        projectId: proj_123
6        branch: main
7    - event: scm.pull_request   # SCM pull request
8      filters:
9        projectId: proj_123
10        state: opened
11    - event: tracker.issue      # Jira/backlog issue event
12      filters:
13        projectId: proj_123

d. Workflow Call Trigger (workflow_call)

Called by other workflows:

1on:
2  workflow_call:
3    inputs:
4      scope:
5        type: string
6        required: true
7    outputs:
8      summary:
9        value: ${{ needs.final-job.outputs.summary }}

3. Concurrency Control

Prevents multiple concurrent runs of the same workflow:

1concurrency:
2  group: requirements-for-${{ inputs.project_id }}
3  mode: queue  # Options: allow, queue, cancel_in_progress, skip

• allow — Allow multiple runs simultaneously
• queue — Queue runs, execute one at a time
• cancel_in_progress — Cancel running workflow, start new one
• skip — Skip new trigger while one is running

4. Permissions

Declares what resources the workflow can access:

1permissions:
2  repos: read           # Read-only SCM access
3  kb: limited          # Limited KB access
4  backlog: write       # Full backlog write access
5  artifacts: read      # Read-only artifact access
6  integrations: read   # Read-only integration access

Options: none, read, limited, write

5. Variables

Static variables available to all jobs:

1vars:
2  organization: "Acme Corp"
3  max_iterations: 5
4  review_template: "enterprise"

Access in jobs: ${{ vars.organization }}

6. Jobs

Jobs are the actual work units. See Jobs & Execution below.

Jobs & Execution

A job is a single unit of work in a workflow. Jobs can run in parallel, in sequence, or with conditional logic.

Basic Job Structure

1jobs:
2  analyze-requirements:
3    title: Analyze Project Requirements
4    needs: []                    # Dependencies
5    if: ${{ success() }}         # Conditional
6    strategy:                    # Matrix/dynamic expansion
7      matrix: { ... }
8    uses: xema/agent          # Action to run
9    with:                        # Inputs to action
10      task: Analyze requirements
11    outputs:                     # Extract outputs
12      summary: ${{ result.summary }}
13    timeout: "1h"               # Job timeout
14    retry:                       # Retry config
15      maxAttempts: 3
16      backoffCoefficient: 2.0

Action References

Actions are referenced with uses:

1uses: <namespace>/<action>@<version>

Examples:

• xema/agent — Invoke an LLM agent
• xema/review — Reviewer pool over one or more subjects, optional in-loop redraft (humans + agents mix)
• xema/emit-artifact — Save artifact to store
• xema/decision-gate — Pinned-version approval gate
• software-dev/create-repository — Create SCM repository

Job Dependencies

Control execution order using needs:

1jobs:
2  step1:
3    uses: xema/agent
4    with: { task: "Step 1" }
5
6  step2:
7    needs: [step1]              # Wait for step1
8    uses: xema/agent
9    with: { task: "Step 2" }
10
11  step3:
12    needs: [step1, step2]       # Wait for both
13    uses: xema/agent
14    with: { task: "Step 3" }

Conditional Execution

Run jobs conditionally with if:

1jobs:
2  build:
3    uses: xema/agent
4    with: { task: "Build" }
5
6  deploy:
7    needs: build
8    if: ${{ inputs.deploy == true }}
9    uses: xema/agent
10    with: { task: "Deploy" }
11
12  notify:
13    needs: [build, deploy]
14    if: ${{ failure() }}        # Only if previous steps failed
15    uses: xema/webhook

Condition Functions:

• success() — Previous job succeeded
• failure() — Any ancestor job failed (including by timeout)
• cancelled() — The run was cancelled (can be true together with failure())
• timedOut() — Any ancestor job failed because its effective timeout elapsed
• always() — Always run

Matrix Expansion

Run a job multiple times with different inputs (static or dynamic):

Static Matrix (Compile-Time)

Defined at workflow authoring time:

1jobs:
2  build-all-platforms:
3    strategy:
4      matrix:
5        os: [ubuntu, windows, macos]
6        version: [20, 21, 22]
7        architecture: [x86_64, arm64]
8      maxParallel: 6           # Limit concurrency
9    uses: xema/agent
10    with:
11      os: ${{ matrix.os }}
12      version: ${{ matrix.version }}
13      architecture: ${{ matrix.architecture }}

This creates 3 × 3 × 2 = 18 parallel jobs.

Dynamic Matrix (Runtime)

Expand based on runtime data:

1jobs:
2  discover-services:
3    uses: xema/agent
4    with:
5      task: List all microservices
6    outputs:
7      services: ${{ result.service_list }}
8
9  deploy-each-service:
10    needs: discover-services
11    strategy:
12      dynamic:
13        from: ${{ needs.discover-services.outputs.services }}
14        as: service
15        maxEntries: 50
16    uses: xema/agent
17    with:
18      service: ${{ dynamic.service }}

Compilation Model

Workflow Lifecycle

1YAML Workflow Source
2       ↓
3   Parse & Validate
4   (Against JSON schema)
5       ↓
6   Version-Pin Actions
7   (Resolve xema/agent → specific build)
8       ↓
9   Bind Trigger Inputs
10   (Validate against input schema)
11       ↓
12   Build Job DAG
13   (Topological sort)
14       ↓
15   Evaluate Static Expressions
16   (Compile-time constants)
17       ↓
18   Compute Determinism Hash
19   (SHA256 of workflow + inputs)
20       ↓
21   Emit CompiledRun
22   (Immutable execution plan)
23       ↓
24   Execute on Xema Workflow Runtime
25   (Deterministic, repeatable)

Deterministic Compilation

Key principle: Same (workflow version + trigger inputs) → same CompiledRun → same execution path.

This ensures:

• Reproducibility — Re-run old workflows with same results
• Auditability — Complete execution history
• Safety — No surprises from runtime re-evaluation

The workflow engine computes a SHA256 hash of:

1. Workflow YAML (version)
2. Trigger inputs (values)
3. Action versions (pinned)

This hash is used to replay workflows or retrieve cached results.

Validation

Workflows are validated at compile time:

• Schema validation — YAML structure matches OpenAPI spec
• Action existence — All referenced actions exist and are versioned
• Type checking — Input/output types match declarations
• DAG validation — No circular dependencies
• Permission checks — Actions don't exceed declared permissions

Invalid workflows are rejected immediately with clear error messages. No silent failures.

Workflow DSL Schema

Pin the live JSON Schema in your YAML editor for instant validation and autocomplete:

1# yaml-language-server: $schema=https://xema.dev/schemas/workflow/v1alpha1/Workflow.json
2apiVersion: xema.dev/workflow/v1alpha1
3kind: Workflow
4...

URLs follow the Kubernetes apiVersion convention <group>/<version>/<Kind> so the schema URL is a deterministic function of the manifest's apiVersion + kind:

All public, cached (cache-control: public, max-age=300).

Templates System

Templates enable consistent, reusable workflow and deliverable generation.

Template Types

1. Prompt Templates (Agent Instructions)

System prompts that guide LLM agents:

1Template: agents-md.builder
2Purpose: Guide an agent to create detailed specifications
3Context: role=builder, spec metadata, retry context
4Rendered: Markdown with embedded instructions

Key templates:

• agents-md.builder — Create specifications
• agents-md.gate-reviewer — Review phase outputs
• agents-md.clarification-coordinator — Handle clarifications
• agents-md.interactive — Interactive sessions

2. Deliverable Specs Templates

Markdown templates with Handlebars placeholders for specs:

1# {{projectName}} Requirements Specification
2
3## Overview
4{{overview}}
5
6## Functional Requirements
7{{#each functionalRequirements}}
8- {{this.title}}: {{this.description}}
9{{/each}}
10
11## Success Criteria
12{{successCriteria}}

These templates are:

• Multi-page — Complex documents split across files
• Customizable — Handlebars helpers for rendering logic
• Versionable — Track template changes
• Scoped — Different templates for different complexity levels

3. Session Templates

Reusable session configurations:

1{
2  "name": "requirements-gathering",
3  "type": "interactive",
4  "tools": ["browser", "code-editor", "diagrams"],
5  "context": { "role": "requirements-engineer" }
6}

Template Rendering

Templates use Handlebars syntax:

1{{variable}}              → Replace with value
2{{#if condition}}        → Conditional blocks
3{{#each array}}          → Loop over array
4{{#unless condition}}    → Negation
5{{../parent.value}}      → Access parent context

Templates are rendered with a context object containing:

• Trigger inputs
• Previous job outputs
• Workflow variables
• System variables (time, user, etc.)

Phases & Artifacts

Pipeline Phases

Xema defines 8 coordinated phases in software delivery:

Execution Models

• GLOBAL_SINGLETON — Single instance for entire workflow
• SCOPED_PARALLEL — Parallel instances per scope (e.g., per service)
• SCOPED_PARALLEL_WITH_GROUP_MERGE — Parallel with merge logic

Artifacts

An artifact is a phase-produced deliverable (spec, report, document):

1interface Artifact {
2  id: string
3  versionId: string
4  version: number
5  type: string              // e.g., "requirements_spec"
6  pointer: string           // Content-addressed reference
7  hash: string
8  size: number
9  createdAt: string
10}

Artifacts are:

• Versioned — Track all changes
• Content-addressed — Retrieved by hash
• Immutable — Once created, never modified
• Referenced — Accessible to downstream phases

Execution Model

Xema Workflow Runtime

Workflows execute on the Xema Workflow Runtime, a distributed workflow engine providing:

• Durability — Workflow state survives process crashes
• Scaling — Horizontal scaling via worker pools
• Reliability — Automatic retry, timeout handling, deadletter queues
• History — Complete execution history and audit trail

Workflow Execution

1Xema Workflow Run: rootRunWorkflow
2    ├── Job 1 (Activity)
3    │   └── Execute action (agent, review, etc.)
4    │
5    ├── Job 2 (Activity)
6    │   └── Execute action
7    │
8    └── Gate (Child Workflow)
9        └── humanApprovalWorkflow
10            ├── Wait for decision
11            ├── Apply timeout action
12            └── Continue or fail

Activities

Activities are the executable units in workflows:

• xema/agent — Invoke an LLM agent
• xema/review — Reviewer pool with optional redraft loop
• xema/emit-artifact — Save artifact
• xema/decision-gate — Pinned-version approval gate
• xema/webhook — Send webhook
• xema/http — HTTP request
• Domain-specific actions (SCM, backlog, etc.)

Task Queues

Activities are routed to specific task queues:

• xema_default — General activities
• xema_agent — Agent invocations (specialized workers)
• xema_human — Human approval workflows

Platform worker

The platform's own background workflows (the ones that keep the platform running, as opposed to the workflows you author) run on the platform worker, shipped as the xema-platform-worker base biome. It is a worker component, not a request-serving service, and it executes both workflows and activities. It polls one task queue per domain, and each queue is named xema-platform-worker:<domain>. The domains are:

These queues carry platform sweeps and cascades that belong to no single organization, so they are not fair-shared per organization. Your own workflows do not run here.

Mounts & Filesystem

Agent jobs run in a workspace filesystem with mounted sources. The published Agent owns that workspace composition; the workflow names the Agent through agentRef.

Agent-owned workspace composition

agentRef is the sole Agent and workspace source for the current Agent action:

1jobs:
2  implement-feature:
3    uses: xema/agent
4    with:
5      agentRef: engineering@5
6      deliverableSpecRef: implementation-record@2
7      agentContext:
8        prompt: Implement the approved change.

At dispatch, Xema resolves the published Agent revision and obtains its mounts, persistence, Skills, tools, sub-agents, and runtime requirements. The same composition powers Interactive Sessions. Workspace Manifests remain an authoring and packaging format, but workflow YAML does not override the Agent's workspace with separate manifest, composition, or inline-mount inputs.

Mount Sources

• Artifact collections — Previous workflow artifacts
• KB spaces — Knowledge base content
• SCM repositories — Git repositories
• Session attachments — Files from sessions
• Deliverable specs — Template specifications
• Static literals — Embedded content

Access Modes

• Read-only — Cannot modify mounted content
• Read-write — Can modify (only for writable mounts)

Example

1mounts:
2  - path: /artifacts
3    source:
4      kind: artifact-store-collection
5      collectionId: coll_123
6  - path: /code
7    source:
8      kind: scm-repo
9      repoRef: github.com/acme/myrepo
10      ref: main
11  - path: /specs
12    source:
13      kind: deliverable-specs
14      contractKey: enterprise-saas

Summary

Xema Workflows are built on core concepts:

1. DSL — Declarative YAML language
2. Compilation — Deterministic, validated, immutable
3. Templates — Reusable, customizable specifications
4. Phases & Artifacts — Coordinated multi-stage delivery
5. Execution — Xema Workflow Runtime-backed, fault-tolerant runtime
6. Mounts — Filesystem access to external resources

Together, these enable powerful, flexible, and safe automation of software delivery.

Next: Read Features & Capabilities to understand what you can build with these concepts.