Loop Engine™

Defining Loops

Yaml Format

Loop definition YAML reference

This format is validated by LoopDefinitionSchema in @loop-engine/dsl.

Top-level fields

  • id: string (required)
  • version: string semver x.y.z (required)
  • description: string (required)
  • domain: string (required)
  • states: StateSpec[] (required, at least 1)
  • initialState: string (required, must exist in states)
  • transitions: TransitionSpec[] (required)
  • outcome: OutcomeSpec (required)
  • participants?: string[]
  • spawnableLoops?: string[]
  • metadata?: Record<string, unknown>

StateSpec

  • id: string (required)
  • description?: string
  • isTerminal?: boolean
  • isError?: boolean

TransitionSpec

  • id: string
  • from: string
  • to: string
  • allowedActors: ("human" | "automation" | "ai-agent" | "webhook" | "system")[]
  • guards?: GuardSpec[]
  • sideEffects?: SideEffectSpec[]
  • description?: string

GuardSpec

  • id: string
  • description: string
  • failureMessage: string
  • severity: "hard" | "soft"
  • evaluatedBy: "runtime" | "module" | "external"

OutcomeSpec

  • id: string
  • description: string
  • valueUnit: string
  • measurable: boolean
  • businessMetrics?: BusinessMetric[]

Annotated example (scm.procurement)

1id: scm.procurement
2version: 1.0.0
3domain: scm
4description: Purchase order lifecycle through settlement
5 
6states:
7  - id: OPEN
8  - id: PO_CONFIRMED
9  - id: RECEIVED
10  - id: INVOICE_MATCHED
11  - id: SETTLED
12    isTerminal: true
13  - id: DISPUTED
14    isError: true
15 
16initialState: OPEN
17 
18transitions:
19  - id: confirm_po
20    from: OPEN
21    to: PO_CONFIRMED
22    allowedActors: [human, automation, ai-agent]
23    guards:
24      - id: approval_obtained
25        severity: hard
26        evaluatedBy: external
27        description: PO must be approved before confirmation
28        failureMessage: PO confirmation requires explicit approval
29 
30outcome:
31  id: po_settled
32  description: Purchase order settled with matched invoice
33  valueUnit: po_settled
34  measurable: true
35  businessMetrics:
36    - id: cycle_time_days
37      label: PO cycle time (days)
38      unit: days
39      improvableByAI: true

Common validation errors

  • initialState not found in states
  • transition from/to references unknown state
  • empty allowedActors
  • duplicate state IDs
  • invalid version format (must be semver)