Skip to main content

Foreground and Background

Every skill in dmx can run in one of two ways: as a manual, one-off command, or as part of a loop.

Foreground: you are the orchestrator​

In foreground mode, you invoke /dmx/* skills one at a time: /dmx/plan, then /dmx/implement-next-phase, then /dmx/validate, and so on. Each skill runs, produces output, and stops. You read the output, decide what to do next, and invoke the next skill yourself.

There is no config governing the sequence, no automated validators, and no state file tracking progress across skills. You are the orchestrator — the sequencing, the judgment calls, and the "is this good enough to move on" decisions are all yours, made fresh each time.

Foreground is the natural mode when:

  • You're new to a loop's skill sequence, or the codebase, and want to see what each step actually produces.
  • The work is novel enough that you want to intervene between steps rather than commit to a fixed sequence.
  • You're debugging why a loop behaved a certain way, by running the same skills manually and inspecting each output.

Background: the loop runtime is the orchestrator​

Running /dmx/run-loop {name} hands orchestration to the loop runtime. The runtime reads a loop config (.dmx/loops/{name}.yaml), executes its skills in order, and does the bookkeeping for you:

  • Persists job and task state to .dmx/jobs/{job_id}/ and .dmx/loop-state.json as it goes.
  • Pauses after each skill for your review when human_gate: true (the default for all five bundled loops), or runs skills back-to-back when human_gate: false.
  • Runs the loop's validators once all skills complete, and applies failure_handling / on_optional_failure to decide whether to pause, fail, or proceed.
  • Chains automatically to the next loop via on_complete when validators pass.

You still review the output either way. With human_gate: true you review at every skill boundary; with human_gate: false you review at the validator/PR boundary instead. What changes between foreground and background is who runs the sequence and what mechanically enforces the checks in between.

Deciding when to relax the gate​

Turning human_gate: false on a loop means fewer stops for your review, so treat it as a deliberate, per-loop decision rather than a default:

  • Read the job history in .dmx/jobs/{job_id}/ for the loop and task type you're considering. Have the required validators been passing consistently? Did you have to revise the output much after gates?
  • Make sure the loop's validators actually check what you care about — required checks are the only thing preventing a bad run from advancing when human_gate is off.
  • Change human_gate (and failure_handling) in the loop's YAML once you're satisfied, and keep watching the job history afterward. You can turn it back on any time a loop starts misbehaving.

In practice​

Start by running skills in the foreground, or with human_gate: true, so you see what the AI does at every step. As a specific loop proves itself for a specific kind of task — based on the job history you've read, not an automated score — relax the gate for that loop.

This is the progression from ad-hoc prompting to a governed, still-human-supervised workflow.