Skip to content
Prev Previous commit
Next Next commit
docs(workforce): document leadFit and openWorkstreamTool (FIX-1920)
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HJZMq1XGNsUeycFS4dXqh9
  • Loading branch information
claude committed Oct 13, 2026
commit 3c254d7dd9ddca9d4d98baaa659dbe2cbfd8673d
24 changes: 21 additions & 3 deletions apps/docs/docs/workforce/projects.md
Original file line number Diff line number Diff line change
Expand Up @@ -202,7 +202,9 @@ export const projectsFlow = defineFlow({
});
```

It returns `openWorkstream` and `updateWorkstream`, the same two as `actions`, `updateWorkstreamTool` for a lead, and `listLeadsTool` for whoever picks a lead (see [Opening workstreams from the coordinator](#opening-workstreams-from-the-coordinator)).
It returns `openWorkstream` and `updateWorkstream`, the same two as `actions`, `updateWorkstreamTool` for a lead, and `listLeadsTool` and `openWorkstreamTool` for a worker that picks a lead and opens the workstream (see [Opening workstreams from the coordinator](#opening-workstreams-from-the-coordinator)).

Pass `leadFit: { model }` to have `openWorkstreamTool` check a worker's pick of lead against the work before it opens. Left out, `openWorkstreamTool` is the same block as `openWorkstream`.

A lead flow must declare the internal entry `workstreamOpenedEntry()` returns, under `internal.actions[WORKSTREAM_OPENED_ENTRY]`. The built-in `agent` flow declares it, and a worker flow of your own spreads it in to let its workers lead. `leadFlows` reads only each flow's `kind` and that entry, so you can pass the flow itself or describe it, as above. A lead flow without the entry is refused when the blocks are built.

Expand Down Expand Up @@ -261,6 +263,7 @@ A workstream id is unique within a project for each owner, so Alice's `checkout`
| `invalid-workstream-id` | The id is empty or holds a `/` |
| `no-such-worker` | The lead isn't a worker on your roster. Another user's worker is refused the same way |
| `cannot-lead` | The lead runs on a flow that isn't in `leadFlows`, or lists no `delegates:` |
| `lead-doesnt-fit` | A worker opened it with `openWorkstreamTool`, `leadFit` is set, and the lead's description doesn't say it does this work. See [Checking the lead fits](#checking-the-lead-fits) |
| `lead-differs` | You already have this workstream open, with another lead. A workstream's lead doesn't change |
| `too-many-workstreams` | You already have 25 open workstreams in the project. Mark one done first. Applies when your installation names a [project coordinator](#talking-to-a-project) |

Expand Down Expand Up @@ -408,9 +411,16 @@ A coordinator holds at most 25 delegates, which is why `openWorkstream` refuses
Your coordinator can open a workstream for you when you ask for work none of your workstreams in the project covers. Add these tools from `defineWorkstreamBlocks` to its catalog:

- `listLeadsTool`, a tool named `listLeads`. It takes no input and returns `{ leads: [{ id, description }] }`: every worker on your roster, your own and the standard ones, that can lead a workstream, as the roster stands when the tool runs. `description` is `null` for a worker without one.
- `openWorkstream`, the same block as the action, named for the catalog with `.as()`. Called without `project`, it opens the workstream in the coordinator's own project. Naming another project is refused with `other-project`, so tell the coordinator to leave `project` out, as the file below does.
- `openWorkstreamTool`, the `openWorkstream` write for a worker, named for the catalog with `.as()`. Called without `project`, it opens the workstream in the coordinator's own project. Naming another project is refused with `other-project`, so tell the coordinator to leave `project` out, as the file below does.

```ts
// The same call as above, with leadFit added.
const workstreams = defineWorkstreamBlocks({
installation,
leadFlows: [agentLeads],
leadFit: { model: "openai/gpt-5.4-mini" },
});

const coordinator = defineCoordinatorFlow({
installation,
delegateFlows: [agent],
Expand All @@ -419,7 +429,7 @@ const coordinator = defineCoordinatorFlow({
catalog: {
...projectCoordinatorTools,
listLeads: workstreams.listLeadsTool,
openWorkstream: workstreams.openWorkstream.as({ name: "openWorkstream" }),
openWorkstream: workstreams.openWorkstreamTool.as({ name: "openWorkstream" }),
},
},
});
Expand All @@ -444,6 +454,14 @@ workstream it returns. When nobody fits, say so and open nothing.

When `openWorkstream` runs in your own coordinator's turn, the new workstream is already one of the coordinator's delegates when the open returns, so the coordinator can hand your ask to it in the same turn. The delegate's target is `<project.visibility>/<project.id>/<id>`, read from the `workstream` the open returns, for example `shared/apollo/checkout`. One worker can lead several of your workstreams, each with its own session and board.

#### Checking the lead fits

`listLeads` returns every worker that can lead, whether or not it suits the work. A coordinator with a single lead tends to pick it even when its description says it does something else. Set `leadFit` to have the open refuse that pick.

With `leadFit: { model }` set, `openWorkstreamTool` makes one call to that model before it opens, asking whether the lead's description (from its worker file, as `listLeads` shows it) says it does the work in the workstream's title and objectives. When the answer is no, the open is refused with `lead-doesnt-fit` and nothing is written. The refusal's message tells the worker to pick another lead from `listLeads`, or, if none does the work, to open nothing and say a worker for it has to be hired first.

The open goes through without a verdict when the model call fails or the lead has no description, so a model outage never stops a workstream opening. Opens through the `openWorkstream` action, such as a user's own open from the app, are never checked.

### Managing the project from the coordinator

Your coordinator can keep its own project's row current: rewrite the brief when the goal shifts, or set the repository once there is one. Give its catalog `setBrief` and `setRepository` from `defineProjectBlocks()`, named for the catalog with `.as()`:
Expand Down
16 changes: 13 additions & 3 deletions packages/workforce/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -1352,7 +1352,7 @@ defineFlow({ kind: "projects", actions: { ...projects.actions, ...workstreams.ac
one of `leadFlows`, that lists delegates (`delegates:`), since a lead runs its workstream through
them. Returns `{ workstream, opened }`; opening it again hands the entry back
(`opened: false`). Refused: `not-a-member` on a shared project, `no-such-worker`, `cannot-lead`
(a lead off `leadFlows`, or one that lists no delegates), `lead-differs`, `invalid-workstream-id`, and `too-many-workstreams` past 25 open workstreams per
(a lead off `leadFlows`, or one that lists no delegates), `lead-differs`, `invalid-workstream-id`, `lead-doesnt-fit` (from `openWorkstreamTool` with `leadFit` set only, see below), and `too-many-workstreams` past 25 open workstreams per
owner per project when the installation names a project coordinator.
- **`updateWorkstream { project, owner?, id, title?, status?, due?, objectives?, report? }`** changes
an entry and returns `{ workstream }`. `status` is a label of up to 80 characters; `"done"` marks
Expand Down Expand Up @@ -1448,13 +1448,23 @@ session the user's entry names, looked up at delivery, so the post lands in that
session.

To let the coordinator open workstreams, add `listLeads: workstreams.listLeadsTool` and
`openWorkstream: workstreams.openWorkstream.as({ name: "openWorkstream" })` to its catalog and name
`openWorkstream: workstreams.openWorkstreamTool.as({ name: "openWorkstream" })` to its catalog and name
both in its `tools:`. Asked for work none of the user's workstreams covers, it lists the leads,
opens a workstream with the one whose description fits (leaving `project` out, so it opens in the
coordinator's own project), and hands the ask to it at `<project.visibility>/<project.id>/<id>`,
built from the returned workstream. Inside the owner's own coordinator turn, the new workstream can
take the hand-off as soon as `openWorkstream` returns.

`listLeads` returns every worker that can lead, whether or not it suits the work, and a coordinator
with a single lead tends to pick it. To have the open refuse that pick, pass `defineWorkstreamBlocks({ installation,
leadFlows, leadFit: { model: "openai/gpt-5.4-mini" } })`: `openWorkstreamTool` then makes one call
to that model asking whether the lead's description (as `listLeads` shows it) says it does the work in
the workstream's title and objectives. If the answer is no, the open is refused with `lead-doesnt-fit` and nothing
is written; the message tells the worker to pick another lead from `listLeads`, or, if none does the work, to open
nothing and say a worker for it has to be hired first. A failed call, or a lead with no description,
lets the open through. Without `leadFit`, `openWorkstreamTool` is `openWorkstream`. Opens
through the `openWorkstream` action, such as a user's own open from the app, are never checked.

## Workers as data

A worker is data: a row its owner holds in their user scope, or a standard worker your files
Expand Down Expand Up @@ -1879,7 +1889,7 @@ the root exports, and reaches no Node built-in.
| `WorkerCapabilitySelection` | What a worker file's `capabilities:` key parses to — capability name to the presets that worker wants. Read by the built-in `agent` worker flow; validated at the hire. |
| `defineProjectsCollection()` / `definePrivateProjectsCollection()` | The shared projects (`projects/*` at org scope) and the private ones (the same keys at each user's scope), both shared across flows and browser-readable through `expose`. Every call returns the same declaration, so they never conflict. `defineProjectFilesCollection` and `definePrivateProjectFilesCollection` declare the files; neither has a browser read. |
| `defineProjectBlocks()` | Returns `{ createProject, setRepository, setBrief, readProject, listProjects, readProjectFiles, actions }`. See [Projects](#projects). |
| `defineWorkstreamBlocks({ installation, leadFlows })` | Returns `{ openWorkstream, updateWorkstream, updateWorkstreamTool, listLeadsTool, actions }`. Each lead flow declares `workstreamOpenedEntry()` under `internal.actions[WORKSTREAM_OPENED_ENTRY]`, as the built-in `agent` flow does; one that doesn't throws. See [Projects](#projects). |
| `defineWorkstreamBlocks({ installation, leadFlows, leadFit? })` | Returns `{ openWorkstream, openWorkstreamTool, updateWorkstream, updateWorkstreamTool, listLeadsTool, actions }`. `openWorkstreamTool` is the open for a worker; with `leadFit: { model }`, it refuses with `lead-doesnt-fit` when the lead's description doesn't say it does the work. Each lead flow declares `workstreamOpenedEntry()` under `internal.actions[WORKSTREAM_OPENED_ENTRY]`, as the built-in `agent` flow does; one that doesn't throws. See [Projects](#projects). |
| `readProject` / `projectProgress(entries, now)` / `STALE_AFTER_MS` / `DONE_STATUS` | A project's row, entries and progress, and the progress function itself (also from `./browser`): counts by status, objectives met, the next due date, and the entries not done and unchanged for `STALE_AFTER_MS` (seven days). `"done"` is the one status with a meaning. |
| `parseWorkstreamEntry(path, state)` | One entry read off its storage key and checked against `workstreamEntrySchema`, with its `project`, `owner` and `id`; `undefined` for a key that isn't an entry. Also from `./browser`, for a browser reading entries through the resource routes. |
| `projectCoordinatorTools` | `{ readProject }`, the project coordinator's tool: put it in `defineCoordinatorFlow({ agent: { catalog } })` and name it in the coordinator's `tools:`. Add `setBrief` and `setRepository` from `defineProjectBlocks()` for it to manage its own project. |
Expand Down
Loading