Designing workflows

Move toward the more powerful mechanism only when the less powerful mechanism cannot adequately express the task.

• Do not ask an agent to decide something the workflow already knows.
• If you know how to do it, encode it.
• Use agents where judgment or genuine uncertainty remains.
• Give each agent a specific purpose and bounded responsibility.
• Supply known context explicitly rather than asking agents to rediscover it.
• Prefer deterministic validation and control flow when success conditions are known.
• Put sequencing, retries, lifecycle, cleanup, and anything else you already know how to do into the workflow rather than prompts whenever possible.
• Prefer composing bounded agents over giving one autonomous agent responsibility for an entire known multi-step procedure.
• When repeated executions show that an agent makes the same decision in the same way, consider moving that decision into the program.
• Keep workflow semantics independent of the execution environment and model/provider assignments when possible.

Don't give an agent autonomy it doesn't need.

Don't keep paying an agent to figure out something you already know how to do.

Agent: find the issue, inspect the
repository, determine the relevant
standards, create a worktree,
implement it, test it, review it,
fix problems...

<Repository name="project"
            url={props.repository}>
  <Worktree name="implementation"
            branch={props.branch}>
    <Implementor issue={props.issue} />
    <Reviewer />
  </Worktree>
</Repository>

Both approaches may accomplish the goal. The xmd version encodes everything we already know how to do and reserves agent autonomy for the parts that still require judgment. It does not eliminate agents or make them deterministic.

A task may start with a coding agent because nobody knows how to do it yet. The agent discovers a successful way to accomplish it. As that way becomes understood and repeated, move the known parts into the program. Agents remain where genuine judgment or uncertainty remains.

As a workflow matures, it should generally become more program and less prompt. This is not about eliminating AI. It is about reserving AI for the places where intelligence is actually valuable.

The workflow owns what happens. The agent owns the judgment assigned to it. The environment owns how and where it runs, including which model or provider fulfills each role. Once known behavior is encoded, run the same workflow locally, in CI, or in another sandbox without redesigning it around that environment.

When you don't know how, let an agent figure it out. Once you know how, make it a program. Then run that program anywhere.

xmd is not primarily an alternative to production-agent frameworks or durable cloud workflow systems. Production agents are applications with dedicated infrastructure and engineering attention. xmd is especially useful for the agentic work on the way to production — implementation, review, testing, debugging, releases, migrations, investigation, CI, repository maintenance, and development automation that need reliability without a dedicated workflow application.

JavaScript is appropriate when the problem genuinely requires general-purpose computation. It should not become the default way to express workflow semantics. Prefer xmd's declarative primitives and composition model when they naturally represent the intent.

If something that belongs in a workflow is unexpectedly difficult to express, requires a large JavaScript workaround, or repeatedly needs the same workaround, treat that as feedback about xmd itself. File an issue describing what you were trying to accomplish, why the existing primitives made it difficult, and the workaround you needed.

An AI helping author xmd should not enthusiastically generate a large JavaScript workaround for a missing generally useful primitive and call the problem solved. If the workflow is complicated because the problem is complicated, that is fine. If it is complicated because xmd makes the problem difficult to express, tell us.

Before using an Agent, ask whether the operation actually requires model judgment. Do not delegate context discovery when the workflow already knows the context. Prefer deterministic validation and control flow over asking an agent to decide known conditions. Future component reference pages should link back to Designing workflows rather than repeat this philosophy.