# 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

1. Give a card the **Plan a workstream** recipe and run it.
2. 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**.
3. 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.
4. 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](https://andon-docs.pages.dev/guide/subtasks-and-relations.md): a card with plain sub-tasks is a checklist, not a workstream.
- [Templates](https://andon-docs.pages.dev/guide/templates-and-bulk-edit.md): a template's sub-tasks don't start on their own.
