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