Workflows

Workflows define triggers, manual inputs, and lifecycle stages, then run inside a published workspace.

How workflows work

A workflow watches an external system or accepts a manual trigger, creates an agent with scoped access from its workspace, injects event context, and tracks the work through issue, code, PR, review, and completion states.

Author workflow YAML under .elasticclaw/workflows/, then publish it to a workspace with elasticclaw workflow push.

Workflow file

yaml

schema_version: v1
name: triage
enabled: true

trigger:
  github_issues:
    event: issue_labeled
    repositories:
      - my-org/my-app
    states:
      - open
    labels:
      - agent-ready
    exclude_labels:
      - do-not-automate
    labelers:
      - "*"

provider: daytona
tags: ["triage"]
color: teal

secret_refs:
  GITHUB_TOKEN: github_app

enable_manual_trigger: true
inputs:
  - name: issue
    type: string
    required: true

stages:
  - id: working
    label: Working
    entry: true
    on_enter:
      remove_labels: [agent-ready]
      add_labels: [agent-working]
      inject: |
        Issue: {{.Issue.Identifier}} — {{.Issue.Title}}
        URL: {{.Issue.URL}}

        Read CONTEXT.md and start working.

  - id: pr_opened
    label: PR Opened
    triggers:
      - message_contains: "[DONE]"
    on_enter:
      add_labels: [needs-review]
      remove_labels: [agent-working]

  - id: merged
    label: Merged
    triggers:
      - pr_merged: {}
    terminal: true

Workflow fields

name — Workflow identifier inside the workspace.

enabled — Set false to pause the workflow.

trigger.github_issues — GitHub Issues source. Supports issue events, repositories, states, required labels, excluded labels, labelers, and assignee filters.

trigger.linear — Linear source. Supports status-change events, states, team, required labels, excluded labels, and assignee filters.

trigger.jira — Jira source. Supports status-change events, project keys, states, required labels, excluded labels, and assignee filters.

trigger.shortcut — Shortcut source. Supports status-change events, workspace, states, required labels, excluded labels, and assignee filters.

provider — Sandbox provider override for agents created by this workflow.

tags and color — Dashboard metadata for created agents.

secret_refs — Environment variable to workspace secret name map.

inputs — Manual trigger inputs.

concurrency_group — Limit parallel agents by group.

working_status — Move the source issue to this status when the agent starts.

enable_manual_trigger — Allow dashboard and CLI manual triggers.

stages — Lifecycle stages used by the workflow.

Issue trigger label filters

Issue-tracker triggers can require labels and reject labels at the same time. All configured labels must be present, and no configured exclude_labels may be present. Matching is case-insensitive and ignores leading or trailing whitespace.

yaml

trigger:
  github_issues:
    event: issue_labeled
    repositories:
      - my-org/my-app
    labels:
      - agent-ready
    exclude_labels:
      - do-not-automate
      - blocked

Use exclude_labels for labels such as blocked, security-hold, or needs-human-review that should prevent automatic agent creation even when the normal trigger labels are present.

Run commands and gates

Workflow stages can run deterministic commands in the agent workspace, persist structured output, and use gates to choose the next stage. This is useful for tests, security scanners, deploy previews, CodeBuild jobs, or any tool that can print JSON.

yaml

stages:
  - id: validation
    label: Validation
    triggers:
      - message_contains: "[DONE]"
    on_enter:
      run:
        command: python3 scripts/validate.py
        output: validation
        timeout: 30m
    gate:
      output: validation
      pass:
        path: status
        values:
          - clean
      fail:
        path: status
        values:
          - issues
          - error
      required: true
      treat_skipped_as_pass: true

  - id: create_pr
    label: Create PR
    triggers:
      - gate_result:
          stage: validation
          verdict: pass
    on_enter:
      inject: |
        Validation status: {{ .Outputs.validation.status }}.
        Create the PR now.

  - id: fix_validation
    label: Fix Validation
    triggers:
      - gate_result:
          stage: validation
          verdict: fail
    on_enter:
      inject: |
        Validation failed: {{ .Outputs.validation.reason }}
        Fix the issue, commit locally, then say [DONE].

Commands should print a JSON object to stdout. ElasticClaw also accepts noisy stdout when the final line is JSON, such as shell trace output followed by {"status":"clean"}. treat_skipped_as_pass is for missing or skipped outputs that should continue through gate_result: pass.

Failure feedback

If a workflow-created agent stops because provisioning, bootstrap, workspace setup, a workflow command, a required gate, or an issue action fails, ElasticClaw marks the run failed and posts a sanitized issue-tracker comment when the workflow has issue context. The comment summarizes what failed and suggests the next diagnostic step without dumping raw logs or secrets.

Failure comments are best-effort. If the tracker token cannot comment, the dashboard and run status still show the failure.

Review stages

A judge stage runs a model-backed review over bounded inputs such as the issue, current diff, captured test output, or selected files. Use judge stages for subjective review, and gates for deterministic tool results.

yaml

stages:
  - id: review
    label: Review
    triggers:
      - message_contains: "[READY_FOR_REVIEW]"
    on_enter:
      judge:
        model: anthropic/claude-sonnet-4-6
        inputs:
          - issue
          - git_diff
          - test_output
        output: review_result
        instructions: |
          Decide whether the implementation satisfies the issue.
        require:
          verdict: pass

  - id: fix_review
    triggers:
      - judge_verdict: fail
    on_enter:
      inject: |
        Review failed. Apply the requested fixes and say [READY_FOR_REVIEW].

judge_verdict matches the most recent judge verdict for the workflow. Keep judge branches unambiguous; use deterministic gates when a transition must be scoped to a specific tool stage.

CLI commands

bash

elasticclaw workspace create --name my-app
elasticclaw workspace push my-app
elasticclaw workflow push --workspace my-app .elasticclaw/workflows/triage.yaml

elasticclaw workflow list --workspace my-app
elasticclaw workflow show triage --workspace my-app
elasticclaw workflow trigger triage --workspace my-app --input issue=ENG-123