Skip to main content
.lobsterX is Forge’s workflow definition format. Every prescriptive workflow is a single YAML file declaring steps, roles, dependencies, and failure policies. The format is Zod-validated at parse time via packages/shared/src/lobsterx-schema.ts. Invalid definitions are rejected before any step dispatches.

​
Steps

The atomic units of work. Each step defines:
FieldDescription
idUnique identifier (snake_case)
commandInstruction sent to the agent. Supports ${arg} interpolation.
roleAbstract agent assignment, resolved at runtime via role bindings
depends_onDAG edges — step waits until all listed steps complete
inputs / outputsTyped data flow with JSON Schema validation
timeoutMax execution time in seconds (default: 600)
on_failurehalt, skip, retry_once, or retry_once_then_escalate

​
Phases

Visual groupings of steps for dashboard rendering. Phases define timeline “chapters” in Burgundy. Steps within a phase run in parallel if their dependencies allow it. Phases do not affect execution order — the DAG does.

​
Roles

Abstract agent assignments resolved at runtime. A role like reviewer maps to a concrete agent through deployment role bindings. Roles declare description and required_skills to guide assignment.

​
Conditions

Step-level conditionals for branching. A step with condition: "${include_legal} == true" evaluates against runtime args and prior step outputs. Steps with false conditions are skipped without contacting a gateway.

​
Example

name: vendor-review
version: 1
steps:
  - id: gather_data
    role: researcher
    command: "Research ${vendor_name} across public sources"
    timeout: 300
  - id: score_risk
    role: analyst
    command: "Score risk for ${vendor_name} from 1-10"
    depends_on: [gather_data]
    stdin: $gather_data.stdout
    on_failure: retry_once
Naming: Step IDs use snake_case. Workflow names use kebab-case.
In Burgundy: Build workflows visually in the workflow builder. ->