Features & Capabilities

This document outlines all major features available in Xema Workflows and when to use them.

Table of Contents

  1. Multi-Phase Pipelines
  2. Intelligent Execution
  3. Human Collaboration
  4. Dynamic Job Expansion
  5. Data Flow & Expressions
  6. Error Handling & Retry
  7. Concurrency Control
  8. Timeouts & Deadlines
  9. Conditional Execution
  10. Artifact Management
  11. Webhooks & External Triggers
  12. Permission-Based Access Control

Multi-Phase Pipelines

What It Is

Workflows orchestrate software delivery across 8 coordinated phases:

  1. Brainstorming — Initial ideation and scope definition
  2. Clarification — Resolve ambiguities and questions
  3. Requirements — Detailed specifications
  4. Architecture — System design and technical approach
  5. Delivery Planning — Implementation roadmap
  6. Engineering — Development and coding
  7. Governance — Quality assurance and compliance
  8. Deployment — Release and rollout

How It Works

Each phase:

  • Produces artifacts — Specifications, reports, documentation
  • Has its own gate — Automated review + optional human approval
  • Runs in parallel or serial — Based on execution model
  • Feeds downstream phases — Artifacts become input to next phase

Example Use Case

yaml
1jobs:
2  brainstorm:
3    uses: xema/agent
4    with:
5      task: Brainstorm project goals and scope
6
7  draft-requirements:
8    needs: brainstorm
9    uses: xema/agent
10    with:
11      task: Create detailed requirements specification
12      context: ${{ needs.brainstorm.outputs.response }}
13
14  requirements:
15    needs: [draft-requirements]
16    uses: xema/review
17    with:
18      reviewId: ${{ format('{0}:requirements', trigger.correlationId) }}
19      # External authoring shape: the producer is a separate step, the
20      # review references it via `subject` + `redraft.step`. On reject,
21      # the engine re-dispatches `draft-requirements` with the prior
22      # reviewer feedback merged into `agentContext.review`.
23      subject: ${{ needs.draft-requirements.outputs.structuredOutput }}
24      redraft: { step: draft-requirements }
25      reviewers:
26        # Mixed pool: a quality-checker agent (mandatory, demoted to
27        # advisory after 3 rejects) and a human (always mandatory).
28        - kind: agent
29          target: { agentRef: gate-reviewer-quality }
30          mandatory: true
31          agentMaxIterations: 3
32        - kind: human
33          target: { userId: ${{ trigger.actorSubject }} }
34          mandatory: true
35      policy:
36        kind: all_of
37      iterationTimeoutSeconds: 86400
38      onIterationTimeout: reject

When to Use

  • Building complex software projects with multiple stakeholders
  • Need clear handoffs between roles (designers → architects → engineers)
  • Want automated quality gates at each stage
  • Track deliverables and maintain audit trail

Intelligent Execution

What It Is

Workflows can invoke LLM agents to automate intelligent tasks:

  • Analyze requirements
  • Generate specifications
  • Review code
  • Answer questions
  • Extract information
  • Generate reports

How It Works

yaml
1jobs:
2  analyze-requirements:
3    uses: xema/agent
4    with:
5      task: "Analyze the provided requirements and identify gaps"
6      context: ${{ vars.project_context }}
7      tools: [code-editor, browser]      # Tools available to agent
8      mounts:                            # Files agent can access
9        /context: knowledge-base
10        /code: repository
11      temperature: 0.7                   # Creativity level (0.0 = deterministic)
12      maxIterations: 10                  # Max reasoning steps

Agent Capabilities

Agents have access to:

  • Tools — Code editor, browser, file system, diagrams
  • Mounts — Read/write access to knowledge base, repositories, artifacts
  • Context — Previous artifacts, specifications, instructions
  • Memory — Multi-turn conversation history
  • Reasoning — Step-by-step problem-solving

When to Use

  • Automating complex analysis tasks
  • Generating specifications from high-level requirements
  • Code review and quality analysis
  • Knowledge extraction and synthesis
  • Report generation

Human Collaboration

What It Is

Workflows can pause and wait for human decisions:

  • Approval gates before proceeding
  • Manual reviews with feedback
  • Clarification rounds with questions
  • Voting/quorum-based decisions

Decision Gates

yaml
1jobs:
2  requirements-gate:
3    needs: requirements
4    uses: xema/decision-gate
5    with:
6      title: Approve requirements
7      subjectArtifacts: ${{ needs.requirements.outputs }}
8      timeoutSeconds: 604800       # 7 days
9      onTimeout: reject            # approve | reject
10      recipients:
11        - kind: human
12          target: { userId: [email protected] }
13        - kind: human
14          target: { userId: [email protected] }
15      policy:
16        kind: m_of_n
17        m: 1                       # 1 of 2 approvals satisfies the gate

Gates accept three recipient kinds — human, agent (an LLM-driven decider), and endpoint (an HTTP check) — in any combination. The reply policy is one of single, m_of_n, all_of, or any_of.

Approval Decisions

Each reviewer can:

  • Approve — Proceed to next phase
  • Reject — Return to previous phase with feedback
  • Force Approve — Override and proceed (special permission)

Interactive Sessions

Interactive Q&A with users runs through xema/agent — the agent asks clarification questions via inquiries, the user replies, the agent drafts:

yaml
1jobs:
2  clarification-round:
3    uses: xema/agent
4    with:
5      agentRef: clarification-coordinator
6      deliverableSpecRef: clarification-record
7      agentSession: true
8      agentContext:
9        prompt: Clarify the project requirements with the participant.
10        purpose: Clarify project requirements
11        context: ${{ needs.brainstorm.outputs.response }}

Participants can:

  • Ask questions
  • Provide feedback
  • Modify documents in real-time
  • Upload files/attachments

When to Use

  • Require stakeholder sign-off before proceeding
  • Need back-and-forth clarification
  • Want voting/consensus decisions
  • Track approval history and reasoning

Dynamic Job Expansion

What It Is

Matrix expansion runs a job multiple times with different parameters:

  • Static matrices — Defined at workflow authoring time
  • Dynamic matrices — Determined at runtime based on data

Static Matrix

Known at workflow creation:

yaml
1jobs:
2  test-all-platforms:
3    strategy:
4      matrix:
5        os: [ubuntu-22.04, windows-2022, macos-13]
6        python-version: [3.10, 3.11, 3.12]
7        include:
8          - os: ubuntu-22.04
9            python-version: "3.13"  # Test 3.13 only on Ubuntu
10      maxParallel: 4                 # Limit concurrent jobs
11    uses: xema/agent
12    with:
13      test-suite: "all"
14      os: ${{ matrix.os }}
15      python-version: ${{ matrix.python-version }}

Creates 3 × 3 = 9 jobs (or more with include).

Dynamic Matrix

Unknown until runtime:

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

Number of jobs determined at runtime.

Accessing Matrix Values

In job with matrix expansion:

yaml
1with:
2  os: ${{ matrix.os }}
3  version: ${{ matrix.version }}
4  # Access previous job matrix values:
5  previous_platforms: ${{ needs.build.outputs }}

When to Use

  • Test across multiple platforms/configurations
  • Deploy to multiple regions or environments
  • Process multiple items in parallel
  • Scale workflows based on runtime discovery

Data Flow & Expressions

What It Is

Workflows pass data between jobs using:

  • Inputs — Trigger parameters
  • Outputs — Job results
  • Expressions — Template logic

Inputs

Typed, validated trigger inputs:

yaml
1on:
2  workflow_dispatch:
3    inputs:
4      project_name:
5        type: string
6        required: true
7        description: Name of the project
8      budget:
9        type: number
10        required: false
11        defaultValue: 100000
12      include_testing:
13        type: boolean
14        required: false
15        defaultValue: true

Access inputs: ${{ inputs.project_name }}

Outputs

Extract data from job results:

yaml
1jobs:
2  analyze:
3    uses: xema/agent
4    with: { task: Analyze }
5    outputs:
6      summary: ${{ result.summary }}
7      risks: ${{ result.risks }}
8      budget: ${{ result.budget }}
9
10  report:
11    needs: analyze
12    uses: xema/agent
13    with:
14      summary: ${{ needs.analyze.outputs.summary }}
15      risks: ${{ needs.analyze.outputs.risks }}

Expressions

Template syntax for dynamic values:

yaml
1${{ expression }}

Expression Features:

  • Variable access — vars.org_name, inputs.scope, needs.job.outputs.field
  • Literals — 'string', 42, true, null
  • Operators — ==, !=, <, >, <=, >=, &&, ||, !
  • Functions — success(), failure(), cancelled(), timedOut(), always(), contains(string, substring)
  • Array access — array[0], array[*] (all elements)
  • Object access — object.field, object['field-name']

Example Data Flow

yaml
1vars:
2  organization: "Acme Corp"
3
4on:
5  workflow_dispatch:
6    inputs:
7      project_scope: { type: string, required: true }
8
9jobs:
10  analyze:
11    uses: xema/agent
12    with:
13      org: ${{ vars.organization }}
14      scope: ${{ inputs.project_scope }}
15    outputs:
16      risks: ${{ result.identified_risks }}
17
18  assess-risks:
19    needs: analyze
20    if: ${{ contains(needs.analyze.outputs.risks, 'high') }}
21    uses: xema/agent
22    with:
23      risks: ${{ needs.analyze.outputs.risks }}
24      risk_level: high

When to Use

  • Pass data between workflow jobs
  • Conditionally execute based on previous results
  • Build dynamic parameters
  • Construct complex logic

Error Handling & Retry

What It Is

Built-in automatic retry and failure handling:

  • Automatic retries with exponential backoff
  • Customizable retry policies
  • Fallback actions
  • Error notification

Retry Policy

yaml
1defaults:
2  retry:
3    maxAttempts: 3
4    backoffCoefficient: 2.0        # 1s, 2s, 4s, 8s...
5    initialInterval: 1s
6    maxInterval: 60s
7
8jobs:
9  deploy:
10    retry:
11      maxAttempts: 5               # Override default
12      backoffCoefficient: 1.5
13    uses: xema/agent

Failure Handling

yaml
1jobs:
2  primary:
3    uses: xema/agent
4    with: { task: Primary task }
5
6  on-failure:
7    needs: primary
8    if: ${{ failure() }}
9    uses: xema/webhook          # Notify on failure
10    with:
11      url: https://alerts.acme.com/slack
12      message: "Primary task failed"
13      severity: critical

When to Use

  • Transient errors (network timeouts, rate limits)
  • Long-running operations that may fail temporarily
  • Gradual rollouts (retry with exponential backoff)
  • Alert on persistent failures

Concurrency Control

What It Is

Prevent multiple workflows from running simultaneously:

  • Queue runs sequentially
  • Cancel old runs when new ones trigger
  • Skip duplicate triggers

Configuration

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

Modes

  • allow — Multiple concurrent runs (default)
  • queue — Run one at a time, queue new triggers
  • cancel_in_progress — Cancel running workflow, start new one
  • skip — Skip if another is running

Example

Project with requirement updates:

yaml
1concurrency:
2  group: requirements-${{ inputs.project_id }}
3  mode: queue                      # Process one at a time

If users trigger the workflow 3 times in succession, they'll execute in order: 1 → 2 → 3.

When to Use

  • Prevent race conditions (data corruption, duplicate processing)
  • Enforce single-threaded execution for critical resources
  • Queue-based processing model

Timeouts & Deadlines

What It Is

Automatic timeout of jobs and entire workflows:

  • Per-job timeout
  • Workflow-level timeout
  • Timeout actions (fail, retry, escalate)

Configuration

yaml
1defaults:
2  timeout: "24h"                   # Workflow level
3
4jobs:
5  quick-task:
6    timeout: "5m"
7    uses: xema/agent
8
9  long-task:
10    timeout: "2h"
11    uses: xema/agent
12
13  approval:
14    uses: xema/decision-gate
15    with:
16      title: Final approval
17      timeoutSeconds: 604800       # 7 days
18      onTimeout: reject            # approve | reject
19      recipients:
20        - kind: human
21          target: { userId: ${{ trigger.actorSubject }} }
22      policy:
23        kind: single

When to Use

  • Prevent workflows from hanging indefinitely
  • Long-running tasks need explicit timeout
  • Human approvals need deadline pressure
  • Long-wait operations need failure detection

Conditional Execution

What It Is

Run jobs only if conditions are met:

  • Based on previous job results
  • Based on input values
  • Based on expressions

Condition Functions

  • success() — Previous job(s) 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 regardless

Examples

yaml
1jobs:
2  build:
3    uses: xema/agent
4    with: { task: Build }
5
6  test:
7    needs: build
8    if: ${{ success() }}            # Run only if build succeeded
9    uses: xema/agent
10    with: { task: Test }
11
12  deploy-prod:
13    needs: test
14    if: ${{ inputs.environment == 'production' }}
15    uses: xema/agent
16    with: { task: Deploy to production }
17
18  notify-failure:
19    needs: [build, test, deploy-prod]
20    if: ${{ failure() }}            # Run if any previous job failed
21    uses: xema/webhook

When to Use

  • Different paths for different inputs
  • Skip deployment if tests fail
  • Conditional cleanup/rollback
  • Environment-specific workflows

Artifact Management

What It Is

Store, version, and reference deliverables (specs, reports, documents):

  • Immutable versioning
  • Content-addressed (by hash)
  • Reference in downstream workflows
  • Full audit trail

Emitting Artifacts

yaml
1jobs:
2  create-spec:
3    uses: xema/agent
4    with: { task: Create specification }
5    outputs:
6      spec_id: ${{ result.artifact_id }}
7
8  save-spec:
9    needs: create-spec
10    uses: xema/emit-artifact
11    with:
12      type: requirements_spec
13      content: ${{ needs.create-spec.outputs.content }}
14      metadata:
15        phase: requirements
16        project_id: ${{ inputs.project_id }}
17    outputs:
18      artifact_id: ${{ result.artifactId }}
19      version: ${{ result.version }}

Referencing Artifacts

Access previous artifacts in new workflows:

yaml
1mounts:
2  - path: /previous-specs
3    source:
4      kind: artifact-store-collection
5      collectionId: ${{ inputs.collection_id }}
6
7jobs:
8  next-phase:
9    uses: xema/agent
10    with:
11      task: Based on previous spec, create architecture
12      spec_path: /previous-specs

When to Use

  • Track deliverables across phases
  • Versioning and audit trail
  • Reuse previous work in new phases
  • Feed downstream workflows

Webhooks & External Triggers

What It Is

Trigger workflows from external systems:

  • GitHub pushes, PRs, releases
  • GitLab pushes, merge requests
  • Jira issue creation/updates
  • Custom webhooks
  • Scheduled triggers (cron)

Webhook Triggers

yaml
1on:
2  webhook:
3    - event: scm.push
4      filters:
5        branch: main
6        projectId: proj_123
7    - event: scm.pull_request
8      filters:
9        state: opened
10    - event: tracker.issue
11      filters:
12        type: feature

Scheduled Triggers

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

Trigger Payload Access

yaml
1jobs:
2  process-event:
3    uses: xema/agent
4    with:
5      provider: ${{ trigger.provider }}      # e.g., "github"
6      event: ${{ trigger.event }}            # e.g., "scm.push"
7      repo: ${{ trigger.payload.repo }}
8      branch: ${{ trigger.payload.branch }}
9      commit: ${{ trigger.payload.commit }}

When to Use

  • React to code changes automatically
  • Trigger on external events
  • Periodic reports or maintenance
  • Integration with existing tools

Permission-Based Access Control

What It Is

Workflows declare what resources they can access:

  • Prevents privilege escalation
  • Clear audit trail
  • Security boundary

Permission Scopes

yaml
1permissions:
2  repos: read                      # SCM access level
3  kb: limited                      # Knowledge base access
4  backlog: write                   # Issue tracking access
5  artifacts: read                  # Artifact store access
6  integrations: read               # External integration access

Levels

  • none — No access
  • read — Read-only access
  • limited — Restricted access (read + specific operations)
  • write — Full read/write access

When to Use

  • Enforce security policies
  • Prevent accidental data corruption
  • Compliance and audit requirements
  • Role-based access control

Feature Combinations

Example: Complex Approval Workflow

yaml
1on:
2  workflow_dispatch:
3    inputs:
4      scope: { type: string, required: true }
5
6concurrency:
7  group: requirements-for-${{ inputs.scope }}
8  mode: queue
9
10permissions:
11  kb: write
12  artifacts: write
13
14jobs:
15  draft:
16    uses: xema/agent
17    with:
18      task: Draft requirements
19      scope: ${{ inputs.scope }}
20    outputs:
21      draft_id: ${{ result.artifact_id }}
22
23  technical-review:
24    needs: draft
25    if: ${{ inputs.scope != 'simple' }}
26    uses: xema/decision-gate
27    with:
28      title: Technical review
29      subjectArtifacts: ${{ needs.draft.outputs }}
30      timeoutSeconds: 259200       # 3 days
31      onTimeout: reject
32      recipients:
33        - kind: human
34          target: { userId: tech-leads }
35      policy:
36        kind: single
37
38  pm-review:
39    needs: [draft, technical-review]
40    if: ${{ success() || failure() }}  # Always review
41    uses: xema/decision-gate
42    with:
43      title: Product review
44      subjectArtifacts: ${{ needs.draft.outputs }}
45      timeoutSeconds: 172800       # 2 days
46      onTimeout: reject
47      recipients:
48        - kind: human
49          target: { userId: [email protected] }
50        - kind: human
51          target: { userId: [email protected] }
52      policy:
53        kind: m_of_n
54        m: 2
55      timeout: "2 days"
56
57  publish:
58    needs: pm-review
59    if: ${{ success() }}
60    uses: xema/emit-artifact
61    with:
62      type: requirements_spec
63      content: ${{ needs.draft.outputs.content }}

Summary

Xema Workflows provide a comprehensive feature set for:

✅ Multi-phase orchestration
✅ Intelligent automation (agents)
✅ Human collaboration (approvals, reviews)
✅ Dynamic expansion (matrix, dynamic jobs)
✅ Type-safe data flow (inputs, outputs, expressions)
✅ Error handling (retry, timeout, failure handling)
✅ Concurrency control (queue, cancel, skip)
✅ Conditional execution (if/then logic)
✅ Artifact management (versioning, audit trail)
✅ External integration (webhooks, schedules)
✅ Security (permissions, access control)

Next: Read Integration Guide to understand how external systems interact with workflows.