Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
91 changes: 91 additions & 0 deletions apps/docs/docs/shift-manager/from-a-checkout.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,91 @@
---
title: Working on Shift Manager
sidebar_label: From a checkout

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Naming: Three labels for one page today — file from-a-checkout, sidebar "From a checkout", title/H1 "Working on Shift Manager", overview link "Working on Shift Manager" under "From a clone…". Not wrong, but aligning H1/title/sidebar/link text would match settings.md / DevTool and reduce grep friction.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've partly aligned them: the overview's link and the README's link now both say "From a checkout", matching the sidebar. The title stays "Working on Shift Manager". The sidebar label can't repeat the category name, and the title says what the page is for better than the label does.


Generated by Claude Code

description: "Run Shift Manager from a clone of the flow-state-dev repository: the fsd profile for working on the framework and on Shift Manager itself, and the devteam profile the repository's checks run against."
---

# Working on Shift Manager

If you've cloned the flow-state-dev repository, Shift Manager comes with two Labs ready to open, called profiles. **`fsd`** is the default: a Lab for working on this repository, Shift Manager included. **`devteam`** is the software team the repository's checks run against. Neither is in the published package.

## Before you start

The `fsd` profile's coding agent is Claude Code. Sign in to Claude Code, or set `ANTHROPIC_API_KEY`, before you start. Without either, the Lab refuses to start and says so.

The [Shift Coordinator](../workforce/shift-coordinator.md) answers on a model of its own, so its turns need `ANTHROPIC_API_KEY` or `AI_GATEWAY_API_KEY`. A worker that names no `model:`, such as one the Shift Coordinator hires, answers on the Lab's default model, `openai/gpt-6-luna`, so its turns need `OPENAI_API_KEY` or `AI_GATEWAY_API_KEY`.

To run the scripted coder (`stub`) instead of Claude Code, set `DEVFORCE_LAB_HARNESS=stub`. It writes one file and costs nothing. A `Coder:` line at start names the coder the Lab started with.

## Start it

```bash
pnpm shift-manager:dev
```

That opens the `fsd` profile with `--dev`, which serves Shift Manager's pages from source, so a change to a screen shows as you save it. `pnpm --filter @flow-state-dev/shift-manager start` runs the same profile on the built pages, and builds them first when they're older than their source.

To open the `devteam` profile instead, pass its config, a path from the repository root:

```bash
pnpm shift-manager:dev --config packages/shift-manager/teams/devteam/fsdev.config.mts
```

To open another Lab from a checkout, pass its config:

```bash
pnpm --filter @flow-state-dev/shift-manager dev --config ../my-lab/fsdev.config.mts
```

## The `fsd` profile

The profile is at `packages/shift-manager/teams/devteam/fsd.fsdev.config.mts`. The Lab has two projects from the start. **FSD** is the framework packages, and **Shift Manager** is this app. Both are shared with everyone in the Lab, and both point at this repository. Inbox is empty until a worker asks you something. The projects and the MCP servers they use are defined in `packages/shift-manager/teams/devteam/fsd-projects.mts`.

The Lab keeps its data in SQLite at `packages/shift-manager/.fsdev/fsd.sqlite`, or wherever `FSD_STORE` points. Delete the file to start fresh.

### Asking for work

Ask the Shift Coordinator for work on either project, and say which one, for example "on Shift Manager, make the empty Inbox say who to ask". A coding agent picks it up in a fresh worktree of your checkout, on a branch of its own, and works to this repository's `AGENTS.md` and `CLAUDE.md`.

Before cutting that branch, the Lab fetches the upstream your `main` tracks, usually `origin/main`, and starts from whichever is newer, that upstream or your local `main`. So you don't need to pull first, and commits you haven't pushed are kept. Your own `main`, its files and your index aren't touched.

If your `main` and its upstream each have commits the other lacks, the run is refused before anything is made, and the refusal names both commits. Pull or rebase, or push, then ask again. If the fetch fails, because you're offline for instance, the run starts from your local `main`, and a warning prints where you started Shift Manager.

The Lab pins the URL of each remote and the upstream your branches track the first time it starts with your checkout, and fetches only from those. If you change a remote's URL on purpose, the next run fetches nothing, starts from your local `main`, and prints a warning naming a pin file. If you change a branch's upstream, the run still fetches the pinned upstream and prints the same kind of warning. Either way, delete that pin file and restart Shift Manager to accept the change.

A coding run works in your checkout with your trust, the way Claude Code does when you start it there. It can create and move branches, tags and remote-tracking refs in your repository.

Only those two projects get a worktree of your checkout. Apart from that fetch, the Lab reaches no git remote, so a coding run on a project you add yourself, even one on this repository, is refused, naming the repository, and nothing is cloned.

### Reviewing a run

Review the work in the run's worktree, or from your checkout with:

```bash
git log -p <branch> --not main main@{upstream}
```

That shows only the run's commits, whichever of the two it started from. The branch stays checked out in its worktree, so git won't check it out a second time in yours.

### Giving runs Linear

Open [Settings](./settings.md) and paste a Linear API key, and every coding run you ask for on either project can read and update Linear, as you. Each user sets their own. A run for someone who hasn't set one works without Linear and says so.

For runs with nobody at the keyboard, such as the repository's checks or CI, `LINEAR_MCP_API_KEY` stands in for the key of the Lab's owner, the user Shift Manager opens as on your machine, until that user sets one. An `MCP servers:` line in the terminal when it starts says whether the owner has a key.

## The `devteam` profile

`devteam` is a software team, at `packages/shift-manager/teams/devteam/fsdev.config.mts`. Its workers' files sit beside the config; the [`teams/devteam` README](https://github.com/fixpoint-labs/flow-state-dev/tree/main/packages/shift-manager/teams/devteam) lays out the tree and the checks that run against it.

An EM worker leads workstreams and files the coder's tasks on each one's board, and a coder worker runs each task as a supervised coding run. On start the EM asks you to approve one feature, so Inbox has something in it. Three projects exist from the start: Storefront, where the Lab's second user has opened two workstreams, `feature` and `release`, both led by the EM, and Platform and Sandbox, with none. Each user talks to a project through its [project coordinator](../workforce/projects.md#talking-to-a-project), which opens a workstream when you ask it for new work.

Its [Shift Coordinator](../workforce/shift-coordinator.md) is a coordinator with the EM and the coder as delegates. Ask it for feature work with a line like `cart-badge: show a badge on the cart`, in the form `<issue-slug>: <what the feature is>`, and it hands your message to the EM. The EM files the feature as a row on the board, or answers that it filed nothing because your message names no feature.

Rows run on the scripted coder (`stub`), with no model. Set `DEVFORCE_LAB_HARNESS=claude-code` to run them on Claude Code instead; the Lab then checks for a Claude Code sign-in or `ANTHROPIC_API_KEY` at start, as the `fsd` profile does.

The Lab keeps its data in SQLite at `packages/shift-manager/.fsdev/devteam.sqlite`, or wherever `DEVTEAM_STORE` points, so projects, their workstreams and your conversations survive a restart. Delete the file to start fresh.

### Its Shift Coordinator's memory

The Shift Coordinator has [memory](../workforce/shift-coordinator.md#giving-it-memory): working memory within a conversation, a rolling digest across conversations, and the `memory/recall` tool to search it. By default it records nothing, so that memory stays empty; ask it to remember something for later and it says it can't keep it.

Start Shift Manager with `DEVTEAM_MEMORY_CAPTURE=1` to record each conversation into its memory after each answer, at the cost of extra model calls every turn. When the Shift Coordinator hands a request straight to a delegate, it takes no turn of its own, so nothing is recorded for that request. The request can appear as earlier context in a later turn that is recorded. Its memory is kept per user, apart from your other flows.
40 changes: 2 additions & 38 deletions apps/docs/docs/shift-manager/overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,45 +43,9 @@ Add `--dev` and leave it running. When you save a file your Lab loaded, a flow m

If the Lab fails to start after a save, the error prints and Shift Manager waits for the next save. A restart is a new process: a Lab with in-memory stores starts empty each time, so use SQLite if you want your data to survive edits.

### Working on Shift Manager itself
### From a clone of this repository

In this repository, `pnpm shift-manager:dev` opens the `fsd` profile: a Lab for working on this repository with Shift Manager itself. It has two projects from the start. **FSD** is the framework packages, and **Shift Manager** is this app. Both are shared with everyone in the Lab, and both point at this repository. Inbox is empty until a worker asks you something.

Ask the [Shift Coordinator](../workforce/shift-coordinator.md) for work on either project, and say which one, for example "on Shift Manager, make the empty Inbox say who to ask". A coding agent picks it up in a fresh worktree of your checkout, on a branch of its own. Before cutting that branch, the Lab fetches the upstream your `main` tracks, usually `origin/main`, and starts from whichever is newer, that upstream or your local `main`. So you don't need to pull first, and commits you haven't pushed are kept. Your own `main`, its files and your index aren't touched.

If your `main` and its upstream each have commits the other lacks, the run is refused before anything is made, and the refusal names both commits. Pull or rebase, or push, then ask again. If the fetch fails, because you're offline for instance, the run starts from your local `main`, and a warning prints where you started Shift Manager.

The Lab pins the URL of each remote and the upstream your branches track the first time it starts with your checkout, and fetches only from those. If you change a remote's URL on purpose, the next run fetches nothing, starts from your local `main`, and prints a warning naming a pin file. If you change a branch's upstream, the run still fetches the pinned upstream and prints the same kind of warning. Either way, delete that pin file and restart Shift Manager to accept the change.

A coding run works in your checkout with your trust, the way Claude Code does when you start it there. It can create and move branches, tags and remote-tracking refs in your repository.

Review the work in that worktree, or from your checkout with `git log -p <branch> --not main main@{upstream}`. That shows only the run's commits, whichever of the two it started from. The branch stays checked out in its worktree, so git won't check it out a second time in yours.

Only those two projects get a worktree of your checkout. Apart from that fetch, the Lab reaches no git remote, so a coding run on a project you add yourself, even one on this repository, is refused, naming the repository, and nothing is cloned.

Open **Settings** and paste a Linear API key, and every coding run you ask for on either project can read and update Linear, as you. Each user sets their own. A run for someone who hasn't set one works without Linear and says so. For runs with nobody at the keyboard, such as a goal check or CI, `LINEAR_MCP_API_KEY` stands in for the Lab's own user until that user sets a key. An `MCP servers:` line at start says whether the Lab's own user has a key.

The coding agent is Claude Code. Sign in to Claude Code, or set `ANTHROPIC_API_KEY`, before you start. Without either, the Lab refuses to start and says so. To run the scripted coder (`stub`) instead, which writes one file and costs nothing, set `DEVFORCE_LAB_HARNESS=stub`. A `Coder:` line at start names the coder it started with. The Shift Coordinator answers on a model of its own, so its turns need `ANTHROPIC_API_KEY` or `AI_GATEWAY_API_KEY`.

The Lab keeps its data in SQLite at `packages/shift-manager/.fsdev/fsd.sqlite`, or wherever `FSD_STORE` points. Delete the file to start fresh.

`pnpm shift-manager:dev` runs with `--dev`, which serves Shift Manager's pages from source, so a change to a screen shows as you save it. `pnpm --filter @flow-state-dev/shift-manager start` runs the same profile on the built pages, and builds them first when they're older than their source. To open the `devteam` profile instead, pass its config, a path from the repository root:
`pnpm shift-manager:dev --config packages/shift-manager/teams/devteam/fsdev.config.mts`.

To open another Lab from a checkout, pass its config:
`pnpm --filter @flow-state-dev/shift-manager dev --config ../my-lab/fsdev.config.mts`.

### The `devteam` profile

`devteam` is the profile this repository's checks run against. Open it with `--config`, as above.

It's at `teams/devteam/fsdev.config.mts`. It isn't in the published package, because it builds on the repository's own test Labs. It's a software team: an EM worker files features as rows on the team's board, and a coder worker runs each row as a supervised coding run. On start the EM asks you to approve one feature, so Inbox has something in it. Three projects exist from the start: Storefront, with two workstreams, and Platform and Sandbox, with none.

Its [Shift Coordinator](../workforce/shift-coordinator.md) is a coordinator with the EM and the coder as delegates. Ask it for feature work with a line like `cart-badge: show a badge on the cart`, in the form `<issue-slug>: <what the feature is>`, and its instructions have it hand the post to the EM. The EM files that feature as a row on the board, or answers that it filed nothing because the post names no feature.

Rows run on the scripted coder (`stub`), with no model. Set `DEVFORCE_LAB_HARNESS=claude-code` to run them on Claude Code instead; the Lab then checks for a Claude Code sign-in or `ANTHROPIC_API_KEY` at start, as the `fsd` profile does. The Lab keeps its data in SQLite at `packages/shift-manager/.fsdev/devteam.sqlite`, or wherever `DEVTEAM_STORE` points. Delete the file to start fresh.

The Shift Coordinator has [memory](../workforce/shift-coordinator.md#giving-it-memory): working memory within a conversation, a rolling digest across conversations, and the `memory/recall` tool to search it. By default it records nothing, so that memory stays empty; ask it to remember something for later and it says it can't keep it. Start Shift Manager with `DEVTEAM_MEMORY_CAPTURE=1` to record each conversation into its memory after each answer, at the cost of extra model calls every turn. Its memory is kept per user, apart from your other flows. Workers it hires onto the built-in `agent` flow get none.
In a checkout of flow-state-dev, `pnpm shift-manager:dev` opens a Lab for working on the framework and on Shift Manager itself. See [From a checkout](./from-a-checkout.md) for that profile, and for `devteam`, the Lab the repository's checks run against.

## What you see

Expand Down
10 changes: 5 additions & 5 deletions apps/docs/docs/workforce/projects.md
Original file line number Diff line number Diff line change
Expand Up @@ -663,7 +663,7 @@ Put `projectWorkspaceCapability` on the harness manager's `uses`, as in the exam

A project can name MCP servers, and every coding run on the project can use their tools. MCP, the Model Context Protocol, is how an agent reaches a tool outside its checkout: an issue tracker, a docs search, a database. A run gets the project's servers however the work reached it: from a workstream, from the project's conversation, or from a task that names the project.

Three parties each decide one thing. The server running your workers decides which MCP servers exist, and their addresses. A project picks from those names. Each user sets their own key for a server, and a run uses the key of the user it works for, so it acts in that tool as them.
The server running your workers decides which MCP servers exist, and their addresses. A project picks from those names. Each user sets their own key for a server, and a run uses the key of the user it works for, so it acts in that tool as them.

```ts
// the server's config, for example in a Shift Manager Lab
Expand All @@ -678,15 +678,15 @@ mcpServers: { linear: { url: "https://mcp.linear.app/mcp" } }

`setMcpServers` replaces the list whole and returns `{ project }`. Only members can call it. Both writes refuse a name the server doesn't offer with `unknown-mcp-server`, naming the ones it does, and anything that isn't a plain name (lowercase letters, digits and hyphens) with `invalid-mcp-server`. A project row can't hold an address or a key.

FSD holds the connection, not the coding agent. When a run starts, FSD connects to each of the project's servers with the requester's key, and the agent gets the servers' tools. It never gets the key or the address: not on its command line, in its environment, in its MCP config or in its session. The connections close when the run ends.
The server holds the connection, not the coding agent. When a run starts, the server connects to each of the project's servers with the requester's key, and the agent gets the servers' tools. It never gets the key or the address: not on its command line, in its environment, in its MCP config or in its session. The connections close when the run ends.

A project that names no servers gets none: its runs don't pick up MCP servers from the server machine's own Claude Code settings, or the connectors of the Claude account it's signed in with. A list or a key changed while work is running applies from the next attempt.

If the requester hasn't set a key for one of the project's servers, the run goes ahead without it, and its session says which key is missing. The same happens for a name the server stopped offering, and for a server FSD can't connect to.
If the requester hasn't set a key for one of the project's servers, the run goes ahead without it, and its session says which key is missing. The same happens for a name the server stopped offering, and for an MCP server that can't be reached.

Keys are stored in the server's own store, as written. A run with a shell and no sandbox runs as the same operating-system user as the server, so it could read that store. Sandbox the run if that matters, and use a key scoped to what runs need.

Only Claude Code runs get a project's servers today. A Codex or Cursor run on the same project works without them, and says so.
Only Claude Code runs get a project's servers. A Codex or Cursor run on the same project works without them, and says so.

In your own app, give the Claude Code block the resolver and the two collections it reads:

Expand Down Expand Up @@ -749,7 +749,7 @@ A few cases go differently:
- **The base has no upstream**, such as a tag, a commit, or a branch that tracks nothing. It is used as it is, with no fetch.
- **The run already has its branch**, on a retry or a later turn. It's handed back as it was, and nothing is fetched.

Listing the checkout is what allows the fetch, so the upstream doesn't need to be in `remotes.allow`. That list still decides which remotes the host clones. The upstream's URL is checked before git sees it: one that uses a transport helper such as `ext::`, starts with `-`, or uses a scheme other than `https`, `ssh` or `file` isn't fetched, and the server logs why.
Listing the checkout is what allows the fetch, so the upstream doesn't need to be in `remotes.allow`. `remotes.allow` decides only which remotes the host clones. The upstream's URL is checked before git sees it: one that uses a transport helper such as `ext::`, starts with `-`, or uses a scheme other than `https`, `ssh` or `file` isn't fetched, and the server logs why.

Several projects can share one checkout, and their runs work side by side, each in its own worktree on its own branch.

Expand Down
2 changes: 1 addition & 1 deletion apps/docs/docs/workforce/shift-coordinator.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ A worker it hires belongs to the user it is talking to: it is on their roster an

A Shift Coordinator can also run on the built-in `agent` flow. It then answers and changes your roster the same way, but has no delegates and hands nothing on. Name `flow: agent`, leave `routing:` and `delegates:` out (the `agent` flow refuses settings it doesn't declare), and give the `agent` flow the catalog and capabilities shown below.

Shift Manager's [`devteam` profile](../shift-manager/overview.md#the-devteam-profile) ships one on the `coordinator` flow.
Shift Manager's [`devteam` profile](../shift-manager/from-a-checkout.md#the-devteam-profile) ships one on the `coordinator` flow.

## Adding one

Expand Down
Loading
Loading