Phase Types

A taskflow is a directed graph of phases. Each phase is one unit of work — an isolated subagent call, a shell command, or a control decision — and the runtime wires them together with dependsOn. This page walks through all ten phase types the way you will actually meet them: starting with the one you will use 80% of the time, then adding power as the problem demands.

You might be wondering: do I need to learn all ten before I can do anything useful? No. Most flows are built from three or four types. The rest exist for specific situations — human approval, iterative refinement, competing drafts — and you can ignore them until you meet one of those situations.

When to reach for what

A running example

The rest of this page builds a single, realistic flow: review a pull request for security risks. You will see the flow grow from one phase into a full DAG as each new need introduces a new phase type.

Save this as review.json — we will keep extending it:

{
  "name": "review",
  "args": { "dir": { "default": "src" } },
  "phases": [
    {
      "id": "review",
      "type": "agent",
      "agent": "security-reviewer",
      "task": "Review every changed file under {args.dir} for security risks and return a prioritized summary.",
      "final": true
    }
  ]
}

The default: agent

An agent phase is exactly what it sounds like: one subagent receives a task prompt and returns one result. It is the right starting point for almost everything.

{
  "id": "summarize",
  "type": "agent",
  "agent": "writer",
  "task": "Summarize the architecture of src/ in two paragraphs."
}

You will usually want the agent to produce something structured you can branch on. Set output: "json" and pair it with an expect contract — if the output does not match, the phase fails with a precise diagnostic and is eligible for retry.

{
  "id": "triage",
  "type": "agent",
  "output": "json",
  "task": "Classify the severity of this issue. Output only JSON.",
  "expect": {
    "type": "object",
    "required": ["severity", "reason"],
    "properties": {
      "severity": { "enum": ["low", "medium", "high", "critical"] },
      "reason": { "type": "string" }
    }
  }
}

A common performance trick: pre-read files into the prompt with context. Without it, the agent burns a turn exploring; with it, the relevant code is already in the prompt when the task starts.

{
  "id": "review-auth",
  "type": "agent",
  "agent": "risk-reviewer",
  "context": ["src/auth/**/*.ts", "{args.spec}"],
  "contextLimit": 12000,
  "task": "Review the auth implementation against the spec. List every risk."
}

For the running PR-review example, a single agent works for a small PR. But for a large one, the agent has to read every file in one turn, produces a huge transcript, and may miss details. Time to fan out.

Fan out over known checks: parallel

You decide to split the review into several independent checks that can run at the same time. You know the checks up front — there are exactly three of them — so parallel is the right fit.

{
  "id": "checks",
  "type": "parallel",
  "context": ["src/**/*.ts"],
  "branches": [
    { "task": "Find missing auth checks.", "agent": "analyst" },
    { "task": "Find missing input validation.", "agent": "analyst" },
    { "task": "Find hardcoded secrets.", "agent": "analyst" }
  ]
}

Use parallel when:

• You know the branches up front.
• Each branch is independent.
• You want the results concatenated, or you plan to merge them downstream.

A shared context array is read once and shared across every branch, which is cheaper than each branch re-reading the same files.

Fan out over a runtime list: map

Now suppose the PR changes a different number of files every time. You cannot hard-code branches — you have to discover the list first, then review each item. That is exactly what map is for.

{
  "id": "review-each",
  "type": "map",
  "over": "{steps.discover.json}",
  "as": "file",
  "agent": "security-reviewer",
  "task": "Review {file.path} for security risks. Return one paragraph.",
  "dependsOn": ["discover"],
  "concurrency": 4
}

The over expression resolves to an array — usually {steps.somePhase.json} from an upstream agent that returned JSON. The runtime then spawns one subagent per item, with concurrency: 4 bounding how many run at once. Inside the task, {file.path} (or whatever you named with as) interpolates the current item.

Like parallel, map's output is a concatenation of per-item outputs. To turn that into a single answer, reach for the next type.

Merge many results into one: reduce

Both parallel and map produce many outputs. When you want one clean summary, add a reduce phase. It exists purely to make aggregation explicit — semantically it is an agent phase that depends on several upstream phases, but reduce signals intent: "this phase's whole job is to synthesize."

{
  "id": "summary",
  "type": "reduce",
  "from": ["review-each"],
  "agent": "writer",
  "task": "Combine these reviews into one prioritized summary:\n{steps.review-each.output}",
  "dependsOn": ["review-each"],
  "final": true
}

Here is our running example after three types of phases:

{
  "name": "review",
  "args": { "dir": { "default": "src" } },
  "concurrency": 4,
  "phases": [
    {
      "id": "discover",
      "type": "agent",
      "agent": "scout",
      "task": "List changed source files under {args.dir}. Output JSON array of {path}.",
      "output": "json"
    },
    {
      "id": "review-each",
      "type": "map",
      "over": "{steps.discover.json}",
      "as": "file",
      "agent": "security-reviewer",
      "task": "Review {file.path} for security risks. Return one paragraph.",
      "dependsOn": ["discover"]
    },
    {
      "id": "summary",
      "type": "reduce",
      "from": ["review-each"],
      "agent": "writer",
      "task": "Combine these reviews into one prioritized summary:\n{steps.review-each.output}",
      "dependsOn": ["review-each"],
      "final": true
    }
  ]
}

Add a quality gate: gate

Your review tool now produces a summary, but sometimes the summary is wrong. You want a second agent to check it before it reaches the user — and if the check fails, the run should stop cleanly rather than ship a bad summary.

{
  "id": "verify",
  "type": "gate",
  "agent": "reviewer",
  "dependsOn": ["summary"],
  "task": "Does the summary match the reviews? End with VERDICT: PASS or VERDICT: BLOCK."
}

The gate inspects upstream output and emits a verdict. PASS lets the flow continue; BLOCK halts it.

You can avoid spending a token at all with eval: a list of zero-token machine checks. If all pass, the gate auto-passes without an LLM call. If any fail, the LLM task runs as normal.

{
  "id": "lint-pass",
  "type": "gate",
  "dependsOn": ["lint"],
  "eval": [
    "{steps.lint.output} contains '0 errors'",
    "{steps.lint.output} contains '0 warnings'"
  ],
  "task": "Confirm lint is clean. VERDICT: PASS or BLOCK."
}

You might be wondering what happens when a gate blocks. By default (onBlock: "halt") the run ends. Set onBlock: "retry" and the gate will re-run its upstream dependsOn phases and re-evaluate — a self-healing loop, bounded by retry.max:

{
  "id": "quality",
  "type": "gate",
  "onBlock": "retry",
  "retry": { "max": 3 },
  "dependsOn": ["implement"],
  "task": "Does this satisfy all criteria? VERDICT: PASS or BLOCK."
}

For deterministic scoring with an optional LLM-judge fallback, see the score field in the field reference below.

Pause for a human: approval

Some decisions should not be delegated to an agent at all. An approval phase pauses the flow until a human clicks approve, reject, or edit.

{
  "id": "approve-ship",
  "type": "approval",
  "dependsOn": ["verify"],
  "task": "Review the fix before shipping."
}

• Approve → phase output is "approved", flow continues.
• Reject → phase fails, flow aborts (unless optional: true).
• Edit → the typed note becomes the phase output, flow continues.

Reuse a saved flow: flow

When you find yourself re-declaring the same multi-phase block in flow after flow, lift it into a saved flow and call it with flow. This is also how you run a flow generated by another phase — for example, a planner agent emits a JSON DAG and a downstream flow phase executes it.

{
  "id": "research",
  "type": "flow",
  "use": "deep-research",
  "with": { "topic": "{args.topic}" }
}

Pass def instead of use to run an inline or runtime-generated definition:

{
  "id": "execute",
  "type": "flow",
  "def": "{steps.plan.json}",
  "dependsOn": ["plan"]
}

Repeat until done: loop

Some work needs iteration: refine a draft until it passes, fix tests until they go green. You don't know how many tries it will take — the answer depends on the work itself. A loop phase repeats its task until until becomes truthy, output converges, or maxIterations is hit.

{
  "id": "refine",
  "type": "loop",
  "task": "Improve this draft. Return JSON {draft, done}.",
  "until": "{steps.refine.json.done} == true",
  "output": "json",
  "maxIterations": 6,
  "convergence": true
}

The until condition inspects the current iteration's output via {steps.<thisId>.json}. convergence: true (the default) stops early if an iteration's output is identical to the previous one — a fixed point where further work would change nothing.

{
  "id": "fix-tests",
  "type": "loop",
  "task": "Fix the failing tests. Use {reflexion} to learn from prior failures. Return {patch, passes}.",
  "until": "{steps.fix-tests.json.passes} == true",
  "output": "json",
  "maxIterations": 10,
  "reflexion": true
}

The default maxIterations is 10; the hard cap is 100. If until never becomes truthy, the loop stops at the cap and the final iteration's output becomes the phase output.

Compete and pick: tournament

Creative or subjective work benefits from generating several options and choosing the best. A tournament spawns competing variants, then a judge picks a winner (or synthesizes an aggregate answer).

{
  "id": "headline",
  "type": "tournament",
  "task": "Write a punchy headline for this launch post.",
  "variants": 4,
  "judge": "Pick the headline with the strongest hook and clearest promise.",
  "mode": "best"
}

If the variants should differ in approach rather than just random sampling, give each its own task via branches:

{
  "id": "headline",
  "type": "tournament",
  "branches": [
    { "task": "Write a bold, provocative headline." },
    { "task": "Write a clear, benefit-driven headline." },
    { "task": "Write a question-based headline." }
  ],
  "judge": "Pick the best headline.",
  "mode": "best"
}

The judge emits either WINNER: <n> (1-based) or JSON {"winner": n}. With mode: "best" the winning variant is the phase output verbatim; with mode: "aggregate" the judge's synthesized answer is. variants defaults to 3 and caps at 20.

Run a shell command: script

For builds, tests, lint, or file transformations, use script. It runs a shell command with zero tokens — no subagent is involved.

{
  "id": "build",
  "type": "script",
  "run": ["npm", "run", "build"],
  "timeout": 120000
}

The array form is execvp-style direct spawn — safe from shell injection and the recommended default. The string form passes through a shell, which is convenient for pipelines but must not contain {...} placeholders:

{
  "id": "list",
  "type": "script",
  "run": "find src -name '*.ts' | head -20"
}

To pass dynamic values into a script safely, pipe them through input (which supports interpolation) rather than interpolating into run:

{
  "id": "format",
  "type": "script",
  "run": ["npx", "prettier", "--stdin-filepath", "foo.ts"],
  "input": "{steps.generate.output}"
}

The complete PR-review flow

Putting the five most common types together — agent, map, reduce, gate, with a script step for lint — here is the full review flow you can copy and adapt:

{
  "name": "review",
  "args": { "dir": { "default": "src" } },
  "concurrency": 4,
  "phases": [
    {
      "id": "lint",
      "type": "script",
      "run": ["npm", "run", "lint"],
      "timeout": 120000
    },
    {
      "id": "discover",
      "type": "agent",
      "agent": "scout",
      "task": "List changed source files under {args.dir}. Output JSON array of {path}.",
      "output": "json"
    },
    {
      "id": "review-each",
      "type": "map",
      "over": "{steps.discover.json}",
      "as": "file",
      "agent": "security-reviewer",
      "task": "Review {file.path} for security risks. Return one paragraph.",
      "dependsOn": ["discover"]
    },
    {
      "id": "summary",
      "type": "reduce",
      "from": ["review-each"],
      "agent": "writer",
      "task": "Combine these reviews into one prioritized summary:\n{steps.review-each.output}",
      "dependsOn": ["review-each"]
    },
    {
      "id": "verify",
      "type": "gate",
      "agent": "reviewer",
      "dependsOn": ["summary"],
      "task": "Does the summary match the reviews? End with VERDICT: PASS or VERDICT: BLOCK."
    }
  ]
}

The intermediate transcripts stay inside the runtime. Your context window only receives the final output.

Field reference

Everything above covered the common cases. The rest of this page is the exhaustive reference — every field on every phase type, the validation rules, and the per-type requirement matrix. Reach for it when you need a precise answer.

Common fields

Every phase accepts these fields. Some are ignored or forbidden on specific phase types — those exceptions are noted per type below.

Per-type requirement matrix

¹ gate requires task unless score is used. ² flow requires exactly one of use or def. ³ tournament requires task unless branches is used.

Per-type field details

Common errors by phase type

Next

Last updated on