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
    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, labels, labelers, and assignee filters.

trigger.linear — Linear source. Supports status-change events, states, team, 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.

enable_manual_trigger — Allow dashboard and CLI manual triggers.

stages — Lifecycle stages used by the workflow.

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.

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