Workstreams
A workstream is a card whose work is split into steps that run one after another, or side by side, on their own. Each step is a card of its own with its own runs. Use one for work too big for one run, such as “migrate the billing service”: Claude proposes the steps, you approve them, and each step starts once the steps it waits for are done.
The Workstreams page lists every active workstream across all teams, so you can see what is running where and what needs you.
Plan a workstream
- Give a card the Plan a workstream recipe and run it.
- When the plan is ready, the card shows up in Needs you as Plan to review. Open the card: its Workstream section shows the Proposed plan.
- Edit the steps. Each step has a title, a team, and the steps it waits for. Steps that wait for nothing start first; the rest show under Then, or Then, in parallel when several can run at once.
- Click Approve plan. The steps become cards. Or click Discard to drop the plan.
You can also add steps to any card by hand: in its Workstream section, type in Add a step and click Add step.
Run it
Move the workstream’s card into Working, or choose Run steps on it. The workstream’s card has no run of its own: moving it starts each step that waits for nothing. After that:
- A step with Start automatically on moves to Ready and runs once everything it waits for is done.
- A step can Continue in the upstream step’s worktree, so it picks up where the step it waits for left off. A step whose upstream uses another repository gets a new worktree instead.
- The card face shows the step bar and 3/5 steps.
- The workstream’s card moves to Done by itself once every step that isn’t archived is in Done.
- An archived step still counts: 6/7 steps · 1 archived. It leaves the step bar, so a workstream whose other steps are all done is finished even though it reads 6/7.
If a step fails, it shows in Needs you as Step failed, with Retry step.
Coordinated workstreams
A coordinated workstream has an agent in charge of it, the coordinator. Instead of the rules above, it starts each step with instructions, reads the step’s report, accepts the result or sends the step back with what to fix, answers the step’s questions, changes the steps that haven’t started, and asks you only what it can’t decide.
To turn it on, open the workstream’s card. In its Workstream section, switch on Coordinated, pick the
Coordinator machine and click Turn on. You can pick a machine only while it is online and hosts
coordinators; the others are listed with the reason. On the machine, andon policy coordinator on allows it. Pick another machine later to move the
coordinator there. Switch Coordinated off and the steps run on the rules again.
The section then shows:
- what the coordinator is doing: Idle, Deciding (thinking about something that just happened to a step), Waiting on you (it asked you something, ran out of turns or stopped), Offline (its machine is away, so the steps run on the rules until it is back) or Paused
- its turns, such as 12/60 turns, and the machine it runs on
- Start it again, when it has stopped
- Coordinator’s decisions, newest first, in plain words: Started step 2: add the table, Accepted step 2, Sent step 3 back: tests missing. When it changed the steps, the decision lists what it added, archived, renamed, or made wait for another step, as a diff of the steps.
Each decision is also in the history of the card it is about: filter the history with Changes.
Pause and resume
Pause stops new steps from starting; steps already running carry on. Resume lets them start again. Both are on the Workstreams page and in the card’s Workstream section. In a coordinated workstream, Pause pauses the coordinator too: it makes no decisions until you resume, and what happens to the steps meanwhile waits for it.
The Workstreams page
Open Workstreams in the sidebar, under Progress. Each row shows:
- the team’s icon, the card’s title and how many steps are done (2/5, with any archived ones), and Paused when it is paused
- the step bar, and the current step’s pipeline when it has one
- Now: the step in flight, its run state and its machine
- an estimate of when it will finish, from how long its steps have taken
- Coordinator: for a coordinated workstream, what its coordinator is doing (Idle, Deciding, Waiting on you, Offline or Paused), its turns and its machine
Workstreams that need you come first, including ones whose coordinator is waiting on you. Filter by Team or Machine (a coordinator’s machine counts), and turn on Show finished to see the completed ones. Click a title to open the card.
On a phone, the Workstreams address opens Needs you; the page is for wider screens.
Repeat a workstream
A card’s Repeat field runs it on a schedule, such as every Monday, or a Custom (cron)… expression. With Make a new card each time, each run starts a fresh copy of the workstream; otherwise Andon runs this card again.
Related
- Sub-tasks and relations: a card with plain sub-tasks is a checklist, not a workstream.
- Templates: a template’s sub-tasks don’t start on their own.
