Workflow Stages

Workflow stages define the lifecycle of a workflow-created agent: entry instructions, done signals, issue transitions, PR events, and terminal stages.

What are stages?

Stages are the state machine that drives a workflow-created agent through its lifecycle. Each stage has entry conditions, actions, and transitions. ElasticClaw Server injects instructions into the agent as messages at each stage transition.

Stage structure

yaml
stages:
  - id: working
    label: "Working"
    entry: true
    on_enter:
      inject: |
        Read your CONTEXT.md and start working on the issue.
        Narrate your progress as you go. Keep me updated.

  - id: pr_opened
    label: "PR Opened"
    triggers:
      - message_contains: "[DONE]"
    on_enter:
      move_issue: "In Review"
      inject: |
        PR created. Watch for CI results and review comments.

  - id: merged
    label: "Merged"
    triggers:
      - pr_merged:
    terminal: true

  - id: closed_no_merge
    label: "Closed Without Merge"
    triggers:
      - pr_closed:
    on_enter:
      inject: |
        PR was closed without merging. Decide: reopen, new PR, or ask the user.

Tool gates

Stages can run a command and evaluate its structured output before deciding what happens next. The command runs in the agent workspace, and the named output is available to later templates as{{ .Outputs.<name>.<field> }}.

yaml
stages:
  - id: validate
    label: Validate
    triggers:
      - message_contains: "[DONE]"
    on_enter:
      run:
        command: python3 scripts/check.py
        output: check
        timeout: 10m
    gate:
      output: check
      pass:
        path: status
        values: [passed, skipped]
      fail:
        path: status
        values: [failed, error]
      required: true

  - id: create_pr
    triggers:
      - gate_result:
          stage: validate
          verdict: pass
    on_enter:
      inject: |
        Validation passed with status {{ .Outputs.check.status }}.

  - id: fix
    triggers:
      - gate_result:
          stage: validate
          verdict: fail
    on_enter:
      inject: |
        Validation failed: {{ .Outputs.check.reason }}
Gates are deterministic. They inspect command output; they do not ask a model to reinterpret logs.

Stage fields

id — Unique stage identifier (kebab-case)

label — Human-readable label shown in UI

entry: true — Marks the initial stage when an agent is created

terminal: true — Marks a terminal stage (the agent will be terminated)

triggers — Conditions that transition into this stage

on_enter — Actions to run when entering this stage

gate — Optional deterministic pass/fail evaluation over a named run output

Triggers

Each trigger defines a condition. Exactly one field should be set per trigger:

message_contains: "[DONE]" — Matches when an agent message contains this substring (case-insensitive)

gate_result — Matches a previous gate verdict, such as pass or fail

judge_verdict — Matches a model review verdict from a judge stage

output_matches — Matches a persisted output path against one or more expected values

pr_merged: — Triggers when the tracked PR is merged (key presence alone activates it)

pr_closed: — Triggers when the tracked PR is closed without merging

pr_conditions: — Compound conditions that must all pass:

  • ci: "passing" — All check runs are success or skipped
  • reviews: "clean" — No CHANGES_REQUESTED reviews
  • quiet_for: "1h" — No new comments in the last hour

On-enter actions

inject — Sends a user message to the agent

run — Runs a command in the agent workspace and can persist stdout as structured output

dependency_updates — Updates Go and npm dependencies with native tooling and persists structured output

judge — Runs a model-backed review over bounded inputs and persists a verdict

move_issue — Moves the associated Linear, Jira, Shortcut, or GitHub issue. It accepts a status string or { status, issue_id }.

close_issue: true — Closes the associated GitHub issue

add_labels — Adds labels to the associated GitHub issue

remove_labels — Removes labels from the associated GitHub issue

merge_pr: true — Attempts to merge the tracked PR through ElasticClaw Server's GitHub PR merge path

Template variables

inject messages and mapped move_issue.issue_id values can use Go template variables. Automatic issue-triggered workflows expose {{.Issue.Identifier}}, {{.Issue.Title}}, {{.Issue.URL}}, and{{.Issue.Description}}. Manual triggers expose{{.Inputs.name}} values from the workflow inputs.

Default stages

A typical issue workflow has four stages:

  1. working — The agent starts here. Injected with "read CONTEXT.md and start working."
  2. pr_opened — Triggered by [DONE] message. Moves issue to done status.
  3. merged — Triggered by PR merge. Terminal — the agent terminates.
  4. closed_no_merge — Triggered by PR close without merge. Injected with guidance.
Stages are pushed as part of workflow YAML. Edit the workflow file, then run elasticclaw workflow push --workspace <workspace> <file-or-dir>.