Skip to content
5 changes: 5 additions & 0 deletions .changeset/workstream-lead-fit.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
"@flow-state-dev/workforce": patch
---

`defineWorkstreamBlocks` takes an optional `leadFit: { model }` and returns `openWorkstreamTool`: a worker's open first checks, with one model call, that the lead's description says it does the work, and is refused `lead-doesnt-fit` when it doesn't. A user's own `openWorkstream` is never checked (FIX-1920).
28 changes: 25 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,18 @@ 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 check runs only once every other refusal has passed, so a bad id or a lead that can't lead is refused for that reason without a model call. Opening a workstream that is already open, with the same lead, isn't checked again.

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.

The tool's answer says what became of the check in `leadFit`: `{ checked: true }` when the lead passed, or `{ checked: false, why }` when it went unchecked. `why` is `already-open`, `no-description`, or `unanswered:` followed by the model call's error, so a check that has stopped answering shows up in the answers rather than nowhere.

### 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
15 changes: 11 additions & 4 deletions packages/shift-manager/teams/devteam/host.mts
Original file line number Diff line number Diff line change
Expand Up @@ -320,7 +320,8 @@ const forCoding = handler({
* guessed.
*
* `openWorkstream` names its lead: a worker on the user's roster that can
* lead. The project coordinator opens workstreams through the same block.
* lead, and whose description says it does the work. The project coordinator
* opens workstreams through the same block.
*
* The owner is the session's user, so a project the chief of staff creates
* belongs to the user talking to it, who is always a project member; `members` adds
Expand All @@ -347,7 +348,7 @@ export function chiefOfStaffProjectTools(blocks: ProjectBlocks, workstreams: Wor
})
.step(blocks.listProjects)
.step(forCoding),
openWorkstream: workstreams.openWorkstream.as({
openWorkstream: workstreams.openWorkstreamTool.as({
Comment thread
jhoffner marked this conversation as resolved.
Resolved
name: "openWorkstream",
description:
"Open a workstream for the user you are talking to, in a project, by the project's address " +
Expand Down Expand Up @@ -857,8 +858,14 @@ export async function openLab(options: OpenLabOptions): Promise<Lab> {
});
// The workstream writes. A workstream's lead runs on the built-in `agent`
// flow or the EM's `em` flow, each of which declares the entry that starts
// its workstream session.
const workstreamBlocks = defineWorkstreamBlocks({ installation, leadFlows: LEAD_FLOWS });
// its workstream session. A worker's open is checked against the lead's
// description first: told in prose, the small model still opened research
// under the EM, the one lead it had.
const workstreamBlocks = defineWorkstreamBlocks({
installation,
leadFlows: LEAD_FLOWS,
leadFit: { model: "openai/gpt-5.4-mini" },
Comment thread
jhoffner marked this conversation as resolved.
Resolved
});
const { listProjects, ...projectWrites } = chiefOfStaffProjectTools(projectBlocks, workstreamBlocks);
const projectTools = options.withoutProjectList === true ? projectWrites : { listProjects, ...projectWrites };
const flowOf = (workerId: string): string =>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ routing: best-fit
minConfidence: 0.7
delegates: [eng.em, eng.coder]
model: anthropic/claude-haiku-5-5
tools: [hire, fire, listProjects, createProject, setRepository, openWorkstream, memory/recall]
tools: [hire, fire, listProjects, createProject, setRepository, listLeads, openWorkstream, memory/recall]
---

You are the chief of staff for this organization. You have five jobs.
Expand Down Expand Up @@ -85,9 +85,12 @@ what it returns.
`visibility: "private"`, and name nobody else.
- To open a workstream in a project, call `openWorkstream` with the project's
address (its `visibility` and `id`), a short lowercase `id` for the
workstream, its title, and its `lead`: a worker on the user's roster that
leads it. Only a shared project's members open workstreams in it. The user
owns the workstream, and nobody else can change it.
workstream, its title, and its `lead`. Pick the lead from `listLeads`: the
worker whose description says it does this work.
Only a shared project's members open workstreams in it. The user owns the
workstream, and nobody else can change it. When `openWorkstream` refuses your lead because it
doesn't do this work, pick another from `listLeads`; when none does it, open
nothing and tell the user a worker for it has to be hired first.
- A project can name the git repository its code lives in: the remote, the
address you'd pass to `git clone`, never a folder. Pass it as `repository`
to `createProject` when the user names one, or call `setRepository` later
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
---
flow: agent
description: Leads research and planning, where the result is a write-up of findings, options or a recommendation, not software. Files each question as a task for the researcher, and keeps the workstream it leads current; never does the work itself.
delegates: [researcher]
model: openai/gpt-5.4-mini
tools: [updateWorkstream]
---

You lead a workstream for the user who owns it: research or planning, where
the result is a write-up of findings, options or a recommendation.

Hand each piece of work you are asked for to the researcher with
`dispatchTask`: its goal, and `researcher` as its assignee. The goal is all
the researcher reads of the ask, so write it as a sentence that keeps every
name, question and detail the ask gave. A job in two parts is two tasks.
`dispatchTask` returns at once and the researcher starts now, so say you
handed it over, never that it is done. Use `addTask` only to write a task down
for later. Do not do the research yourself.

When a line says a task completed, failed or is waiting on a question, say
what it says, and call `updateWorkstream` with a short status and your latest
report, so everyone reading the project sees where the work stands. Mark it
`done` only when the owner says the workstream is finished.
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,8 @@ is instead.
of their workstreams here holds, open one for it in this turn:

1. Call `listLeads` and pick the worker whose description says it does this
work, such as the EM for a feature. Pick only from what it returns, never
work, such as the EM for a feature, or the general lead for research or
planning. Pick only from what it returns, never
from memory: it lists the only workers that can lead a workstream, and you
are not one of them.
2. Call `openWorkstream` with a short lowercase `id` and a `title` for the
Expand All @@ -51,6 +52,7 @@ of their workstreams here holds, open one for it in this turn:
The ask is the workstream's brief.

When the work belongs to a workstream they already own here, hand it there and
open nothing. When `listLeads` returns nobody whose description fits, say that
open nothing. When `listLeads` returns nobody whose description fits, or
`openWorkstream` refuses your lead because it doesn't do this work, say that
nobody on their roster does this work and open nothing: hiring is the chief of
staff's job.
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
---
flow: agent
description: Researches a question it is given as a task and writes up what it found, with the options, their trade-offs and a recommendation. Writes no code.
model: openai/gpt-5.4-mini
tools: []
---

You research the question your task asks and answer it in a short write-up:
what you found, the options, the trade-offs between them, and the one you
recommend. Say plainly what you could not find out. Do not write code.
75 changes: 67 additions & 8 deletions packages/shift-manager/test/project-workstreams.test.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -53,7 +53,10 @@ type ToolCall = { toolName: string; args: Record<string, unknown> };
/** What the project coordinator's judgment calls on its next turn, one call per step. */
let judgmentCalls: ToolCall[] = [];

/** The judgment runs `judgmentCalls`, then stops; any other generator answers a fixed line. */
/** Whether the lead fit check answers that a lead fits, by the lead and work it was asked about. Every lead fits by default. */
let leadFits: (asked: string) => boolean = () => true;

/** The judgment runs `judgmentCalls`, then stops; the lead fit check answers `leadFits`; any other generator answers a fixed line. */
function scripted(): ModelResolver {
let step = 0;
const judgment: GeneratorModel = {
Expand Down Expand Up @@ -81,9 +84,22 @@ function scripted(): ModelResolver {
return { text: "On it.", finishReason: "stop" };
},
};
return Object.assign((_id: string, block?: string) => (block?.startsWith("coordinator-judgment") ? judgment : agent), {
resolveId: (id: string) => id,
}) as unknown as ModelResolver;
const fit: GeneratorModel = {
modelId: "test/fit",
async generate(options: unknown) {
return { structuredOutput: { fits: leadFits(JSON.stringify(options)) }, finishReason: "stop" };
},
async generateStep(options: unknown) {
return { structuredOutput: { fits: leadFits(JSON.stringify(options)) }, finishReason: "stop" };
},
};
return Object.assign(
(_id: string, block?: string) =>
block?.startsWith("coordinator-judgment") ? judgment : block === "workstream-lead-fit" ? fit : agent,
{
resolveId: (id: string) => id,
},
) as unknown as ModelResolver;
}

let lab: Lab | undefined;
Expand All @@ -92,6 +108,7 @@ let root: string | undefined;

beforeEach(() => {
judgmentCalls = [];
leadFits = () => true;
});

afterEach(async () => {
Expand Down Expand Up @@ -143,9 +160,12 @@ async function ownWorkers(user: User): Promise<RosterEntry[]> {
return (await user.roster()).filter((entry) => !entry.standard).sort((a, b) => a.id.localeCompare(b.id));
}

/** The DevTeam's one worker that can lead a workstream. */
/** The DevTeam's lead for features. */
const EM = "eng.em";

/** The DevTeam's lead for research, planning and other work that isn't building software. */
const GENERAL_LEAD = "general-lead";

/** Open a workstream over HTTP, as an app may, naming the EM as its lead. */
async function openAs(user: User, setup: ProjectSetup, id: string, project: ProjectAddress = APOLLO) {
return runAction(user.clients, setup.flow, readerSessionId(user.clients.userId, setup.flow), "openWorkstream", {
Expand Down Expand Up @@ -225,9 +245,9 @@ describe("opening a workstream by asking the project coordinator (V8b: BR-38 to
expect(await ownWorkers(alice)).toEqual([]);

const pc = await askFor(alice, setup, "checkout", "Please add guest checkout, PERIWINKLE-7319.");
// It was offered only the worker that can lead: the coder, the reviewer and the coordinators lead nothing (BR-42).
// It was offered only the workers that can lead: the coder, the reviewer, the researcher and the coordinators lead nothing (BR-42).
await eventually(async () => ((await leadsOffered(alice, pc)).length > 0 ? true : undefined), "the leads read");
expect(await leadsOffered(alice, pc)).toEqual([[EM]]);
expect((await leadsOffered(alice, pc)).map((ids) => [...ids].sort())).toEqual([[EM, GENERAL_LEAD].sort()]);
expect(await ownWorkers(alice)).toEqual([]);

// The EM leads the entry, and its session is the workstream session.
Expand Down Expand Up @@ -272,7 +292,7 @@ describe("opening a workstream by asking the project coordinator (V8b: BR-38 to
});
const pc = await askFor(alice, setup, "release", "Cut the release, AMBER-4410.", "release-lead");
await eventually(async () => ((await leadsOffered(alice, pc)).length > 0 ? true : undefined), "the leads read");
expect(await leadsOffered(alice, pc)).toEqual([[EM, "release-lead"].sort()]);
expect((await leadsOffered(alice, pc)).map((ids) => [...ids].sort())).toEqual([[EM, GENERAL_LEAD, "release-lead"].sort()]);
const entry = (await readProject(alice.clients, alice.reader, APOLLO))!.entries.find((e) => e.id === "release")!;
expect(entry.lead).toBe("release-lead");
await eventually(async () => ((await holds(alice, entry.sessionId!, "AMBER-4410")) ? true : undefined), "the ask in the hired lead's session");
Expand All @@ -289,6 +309,45 @@ describe("opening a workstream by asking the project coordinator (V8b: BR-38 to
expect((await readProject(alice.clients, alice.reader, APOLLO))!.entries.map((e) => e.id)).toEqual(["release"]);
});

it("refuses research under the EM, whose description says it files features, and opens it under the general lead", async () => {
const { setup, as } = await open();
const alice = await as(ALICE);
// The check is asked about each pick: the EM doesn't do research, by its own description.
const asked: string[] = [];
leadFits = (prompt) => {
asked.push(prompt);
return !prompt.includes(EM);
};
const research = { project: APOLLO, id: "research", title: "Research what to build next", objectives: ["Rank three ideas, SAFFRON-2207."] };
judgmentCalls = [
{ toolName: "listLeads", args: {} },
{ toolName: "openWorkstream", args: { ...research, lead: EM } },
{ toolName: "openWorkstream", args: { ...research, lead: GENERAL_LEAD } },
{ toolName: "handOff", args: { worker: GENERAL_LEAD, target: "shared/apollo/research" } },
];
const pc = await projectCoordinator(alice, setup);
await runAction(alice.clients, "coordinator", pc, "run", { message: "Open a workstream to research what to build next, SAFFRON-2207." });

const { items } = await readSessionItems(alice.clients, pc);
const opens = (items as Array<{ type?: string; blockName?: string }>).filter(
(item) => item.type === "tool_output" && item.blockName === "openWorkstream",
);
expect(opens).toHaveLength(2);
expect(JSON.stringify(opens[0])).toContain("lead-doesnt-fit");
// The check read each lead's own description, from its file.
expect(asked).toHaveLength(2);
expect(asked[0]).toContain("Files each feature as a task for the coder");
expect(asked[1]).toContain("Leads research and planning");

const entries = (await readProject(alice.clients, alice.reader, APOLLO))!.entries;
expect(entries.map((e) => ({ id: e.id, lead: e.lead }))).toEqual([{ id: "research", lead: GENERAL_LEAD }]);
expect((await delegatesOf(alice, pc)).map(({ worker, target }) => ({ worker, target }))).toEqual([
{ worker: GENERAL_LEAD, target: "shared/apollo/research" },
]);
await eventually(async () => ((await holds(alice, entries[0]!.sessionId!, "SAFFRON-2207")) ? true : undefined), "the ask in the general lead's session");
expect(await ownWorkers(alice)).toEqual([]);
});

it("drops the record when she marks the workstream done, and moving it back out of done restores it", async () => {
const { setup, as } = await open();
const alice = await as(ALICE);
Expand Down
Loading
Loading