Shorthand

Sometimes you don't need a DAG. You just want to delegate one thing, or run a few checks at once, or chain two steps where the second needs the first's output. Writing a full phases array for that is overhead.

taskflow accepts three shorthand shapes — task, tasks, and chain — that the runtime desugars into proper flows before validation and execution. This page is a friendly quick reference: what each shape produces, when to reach for it, and the exact full-flow JSON it expands into.

task — delegate one thing

You want to delegate a single piece of work to one agent. That is the whole flow.

{
  "task": "Summarize the architecture of src/",
  "agent": "explorer"
}

The runtime desugars this into a flow with one agent phase, marked final so its output is what comes back:

{
  "name": "task",
  "phases": [
    {
      "id": "main",
      "type": "agent",
      "task": "Summarize the architecture of src/",
      "agent": "explorer",
      "final": true
    }
  ]
}

Best for: one-off delegations where a single agent call is the entire answer.

tasks — run independent checks in parallel

You have a fixed list of things you want checked at the same time. Each is independent; you want them all to run concurrently.

{
  "tasks": [
    { "task": "Audit auth in src/api", "agent": "analyst" },
    { "task": "Audit input validation in src/api", "agent": "analyst" }
  ]
}

This desugars into a single parallel phase whose branches are your tasks. The outputs are concatenated; the phase is final:

{
  "name": "parallel",
  "phases": [
    {
      "id": "parallel",
      "type": "parallel",
      "branches": [
        { "task": "Audit auth in src/api", "agent": "analyst" },
        { "task": "Audit input validation in src/api", "agent": "analyst" }
      ],
      "final": true
    }
  ]
}

Best for: a known list of independent checks you want to fan out and gather.

chain — steps that need the previous output

Each step depends on the one before it. The second step needs to see the first step's result. The third needs the second's. This is a sequential chain.

{
  "chain": [
    { "task": "List the public API of src/lib", "agent": "scout" },
    { "task": "Write docs for:\n{previous.output}", "agent": "writer" }
  ]
}

Each step becomes an agent phase (step1, step2, …) that depends on the previous one. The last step is final. Inside a step's task, {previous.output} resolves to the immediately preceding step's output:

{
  "name": "chain",
  "phases": [
    {
      "id": "step1",
      "type": "agent",
      "task": "List the public API of src/lib",
      "agent": "scout"
    },
    {
      "id": "step2",
      "type": "agent",
      "task": "Write docs for:\n{previous.output}",
      "agent": "writer",
      "dependsOn": ["step1"],
      "final": true
    }
  ]
}

Best for: a pipeline where each step consumes the last step's output. {previous.output} is the chain equivalent of {steps.X.output} in a full DAG.

Pre-reading files with context

All three shapes support context and contextLimit — files to pre-read and inject before the task runs, so the agent doesn't spend turns exploring.

{
  "chain": [
    {
      "task": "List the public API",
      "agent": "scout",
      "context": ["src/lib/**/*.ts"]
    },
    { "task": "Write docs for:\n{previous.output}", "agent": "writer" }
  ]
}

Put context on individual steps. In chain mode, a top-level context is ignored (with a warning) — declare it per step instead. In tasks mode, the union of the top-level context and each step's context is shared across all branches.

Precedence

If you provide more than one shape, the runtime picks one in a fixed order: chain > tasks > task. A spec with both chain and task is treated as a chain; the task is ignored.

Carrying metadata through

Shorthand specs accept the same top-level metadata as a full flow. These are passed through to the desugared definition:

{
  "name": "audit-api",
  "description": "Quick parallel audit of the API layer.",
  "concurrency": 2,
  "tasks": [
    { "task": "Audit auth", "agent": "analyst" },
    { "task": "Audit validation", "agent": "analyst" }
  ]
}

From shorthand to full DAG

Shorthand gets you started fast. When you outgrow it, the path is mechanical — the desugared JSON above is exactly what the runtime sees, so you can copy it, add the fields shorthand can't express, and keep going.

Next

Last updated on