agentJob on its own is enough.
Motivation
Every team has a way work moves. A ticket gets read, someone builds it, someone tests it, a few people review it, and a lead says ship. Nobody draws that on a whiteboard before each ticket. It’s just how the team works. A workflow is that shape written down, in a TypeScript file you version, review and share like anything else you write, and the runtime runs it the same way each time.Two forms
workflow() is the short form: a brief, named roles, and a list of stages,
each an agent, a command, a review panel, a person, or a plain function. The
first run is one:
examples/teams/writer-reviewer-pair.ts (excerpt)
dag() is the full form, and it is what workflow() compiles to. A node is
any job: a seat, a command, a person, a whole workflow(), or a plain
function of your own that reads what earlier nodes produced and decides what
runs next. A Shape Up cycle as one run is a dag whose nodes are workflows:
examples/use-cases/product/shape-up-cycle.ts (excerpt)
fnJob. This one writes a file and reads
the last review’s summary from the context:
examples/command-kickback.ts (excerpt)
workflow(); reach for dag() when a step needs your own
code, a branch, a tournament, or a team inside a team.
Parts
- Steps. Each step is a job: an agent call, a command, a check. The record carries whose work each step was.
- Sequence and dependencies. A pipeline runs steps in order. A graph runs independent steps together and waits where one depends on another. Both are one call.
- Reviews. A review judges another step’s result. A panel passes on the count you set. When a review fails a step, the findings go to the stage that owns the fix, which runs again with them. Feedback loops covers the shapes.
- Decisions for a person. A callback gate stops the run, puts one question in front of someone, and carries on from that step with the answer. No model interprets it.
- Limits. An attempt can carry a time budget, and a step runs again only as many times as you allow. No step can hang the run or burn the budget, and the record says why it stopped.
Descriptions and gates
A step carries two sentences beside its job:desc, what it does, and
gate, what done means. Both go into the plan and the record. An agent
step built with graphContext: true also gets desc in its prompt. In a
workflow(), the writing seat gets both. So does each agent reviewer,
from the stage that declares it. A criterion written beside the code is
hard to write vaguely:
examples/described-team.ts (excerpt)
Example record
Orders
Someone asks for a change: a passkey login, a report export with a header row. On a team that’s a ticket: what’s wanted, why, the constraints, and what done looks like. An order is that ticket, and a workflow is what the team does with it. Inexamples/feature-delivery.ts the order is one line:
build a retry helper that retries failed requests, caps attempts, and stops
when the caller aborts.
The runtime has no order type, no ticket store and no opinion about where
your tickets live. Your application decides what an order holds, where it’s
kept and which workflow runs on it, so it can come from Linear, GitHub or a
text file.
Lifecycle
An order moves through its workflow without waiting for others, gets its reviews and a person’s decisions on the way, and closes when its evidence says the requirements are met. Some orders need more than one workflow. A payment feature is three in a row: implement it, review it for security, release it. Your application starts each when the one before finishes, and runs independent ones together.Properties
Four things travel with an order, linked in the record, so a result reads without the agent’s conversation:- Context. The requirements, designs and constraints the work needs.
- The workflow. The steps that carry it out, as code.
- The output. The files and artifacts the work made or changed.
- The evidence. The checks, reviews and decisions that accepted the output. Proof acceptance binds a review or an approval to the exact bytes it judged.