Loop YAML Schema

Full reference for loop configuration files (.dmx/loops/{name}.yaml).

Top-level fields

Field	Type	Required	Default
name	string	Yes	—
skills	list[string]	Yes	—
trigger	object	No	{type: manual}
goal_state	string	No	""
repeat_until	string | null	No	null
validators	list[object]	No	[]
on_optional_failure	warn | ignore	No	warn
failure_handling	pause | fail	No	pause
human_gate	boolean	No	true
on_complete	object	No	(see below)

name

name: dev

The loop name. Must be non-empty and match the filename stem exactly — a file named dev.yaml must have name: dev, or loading fails.

skills

skills:
  - implement-next-phase
  - commit

Ordered list of skill names to execute. Must contain at least one skill. Skill names correspond to the name field in skill .md files. See Command Reference.

Skills execute in order. When human_gate: true, the loop pauses after each skill.

trigger

trigger:
  type: manual        # or: on_complete

manual: the loop must be started explicitly with /dmx/run-loop name.

on_complete: the loop fires automatically when another loop's on_complete.on_success.trigger_loop references it.

goal_state

goal_state: "All phases implemented and committed, no unchecked tasks remaining"

Plain-English description of what the loop is trying to achieve. Passed to validators in the loop context (goal_state in the input contract). Not persisted to the task state file — it's read fresh from the loop config on each run.

repeat_until

repeat_until: all_phases_complete

If set, the skill sequence repeats until the condition evaluates to true. After each iteration, the condition is checked before validators run.

all_phases_complete: checks .dmx/tasks.md for unchecked - [ ] items. Condition is met when all items are - [x].

Omit (or set to null) for loops that should run once.

validators

validators:
  - tool: run_tests
    checks:
      - name: tests_pass
        required: true
      - name: coverage_threshold
        required: false
  - tool: spec_adherence
    checks:
      - name: scope_matches_spec
        required: true

List of validator tools to run after all skills complete. Each validator:

tool: validator script name. Resolved to validators/{tool}.py in the repo root; falls back to the bundled validator with that name.

checks: named checks to verify in this validator's output. Each check:

• name: must match a check name in the validator's JSON output
• required: true (must pass) or false (warning if fails)

on_optional_failure

on_optional_failure: warn   # or: ignore

What happens when an optional check (required: false) fails:

• warn: warning is emitted, loop advances
• ignore: failure is silently ignored

failure_handling

failure_handling: pause   # or: fail

What happens when a required check (required: true) fails:

• pause: loop pauses. You fix the issue and run /dmx/loop-continue to retry.
• fail: loop terminates. Job is marked failed.

human_gate

human_gate: true   # or: false

When true, the loop pauses after each skill completes and waits for /dmx/loop-continue before proceeding to the next skill (or to validators, if it was the last skill).

When false, skills run back-to-back automatically.

on_complete

on_complete:
  on_success:
    trigger_loop: validate    # or: null
  on_failure:
    trigger_loop: null
  on_warning:
    trigger_loop: null

Three sub-keys, each with a trigger_loop value:

• on_success: all required validators pass
• on_failure: one or more required validators fail
• on_warning: required validators pass but optional validators fail

trigger_loop is either a loop name (starts that loop immediately) or null (loop chain ends).

Default values if on_complete is omitted:

on_complete:
  on_success:
    trigger_loop: null
  on_failure:
    trigger_loop: null
  on_warning:
    trigger_loop: null

Complete example

name: dev
skills:
  - implement-next-phase
  - commit
trigger:
  type: on_complete
goal_state: "All phases implemented and committed, no unchecked tasks remaining"
repeat_until: all_phases_complete
validators:
  - tool: run_tests
    checks:
      - name: tests_pass
        required: true
      - name: coverage_threshold
        required: false
  - tool: spec_adherence
    checks:
      - name: scope_matches_spec
        required: true
      - name: edge_cases_addressed
        required: false
on_optional_failure: warn
failure_handling: pause
human_gate: true
on_complete:
  on_success:
    trigger_loop: validate
  on_failure:
    trigger_loop: null
  on_warning:
    trigger_loop: null