Loops
A loop is the fundamental unit of work in dmx. Every phase of the AI SDLC corresponds to a loop.
A loop is not just a sequence of commands. It is a named, versioned unit of workflow that carries its own skills, trigger, validators, failure policy, human gate, goal state, and chaining behavior. Loops live in .dmx/loops/{name}.yaml in your repository, versioned alongside code, reviewed in PRs.
The five properties of a loop
1. Skills
An ordered list of skills to execute. Skills correspond to slash commands like /dmx/plan, /dmx/implement-next-phase, or /dmx/validate.
Skills run in sequence. When human_gate: true, the loop pauses after each skill and waits for your approval before continuing.
2. Trigger
What starts the loop. Two options:
| Trigger | When to use |
|---|---|
manual | The developer starts the loop explicitly with /dmx/run-loop |
on_complete | The loop fires automatically when the previous loop completes successfully |
The five default loops form a chain: Spec fires Plan, Plan fires Dev, Dev fires Validate, Validate fires Release. Each uses on_complete.
3. Validators
One or more validators run after all skills complete. Validators check the loop's output against the goal state. A loop is not done until all required validators pass.
Each validator has named checks. Checks marked required: true must pass. Checks marked required: false produce a warning on failure but don't block the loop.
See Validators for the full list of bundled validators and how to write custom ones.
4. Failure handling
What happens when a required validator fails. Two modes:
| Mode | Behavior |
|---|---|
pause | Loop pauses. You fix the issue and call /dmx/loop-continue. |
fail | Loop terminates. The job is marked failed. |
pause is the default for all five bundled loops.
5. Goal state
A plain-English description of what success looks like. The goal state is passed to validators as context (goal_state in the validator's input contract).
The human gate
All five default loops have human_gate: true. The loop pauses after each skill and waits for you to review before proceeding.
To advance past a gate:
/dmx/loop-continue
The human gate is what makes loops safe by default. Bad output from a skill cannot advance to the next skill, or trigger the next loop, without your explicit approval.
Loop chaining
When a loop completes successfully, it can start the next loop automatically via the on_complete block. The five defaults form a complete chain:
Spec → Plan → Dev → Validate → Release
Chaining is optional. Set trigger_loop: null in on_complete to end the chain there.
The default loops
| Loop | Skills | Trigger | Chains to |
|---|---|---|---|
| spec | create-ticket | Manual | plan |
| plan | plan | on_complete | dev |
| dev | implement-next-phase, commit | on_complete | validate |
| validate | validate | on_complete | release |
| release | create-pr, update-memory | on_complete | none |
Each loop is described in detail in The Default Loops.
Repeat until
The Dev Loop has repeat_until: all_phases_complete. This tells the loop to repeat its skill sequence until all tasks in tasks.md are checked off.
After each iteration, dmx checks the condition. If unchecked tasks remain, the loop repeats. When all tasks are complete, validators run.
Custom loops
Place a YAML file at .dmx/loops/{name}.yaml to override any default loop or create a new one. The repo-level config always takes precedence over the bundled default.
See Loop Configuration for the full YAML reference.