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.

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

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)

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

move_issue — Moves the associated Linear, 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>.