Teams

Once you have several projects, a common shape is “the output of a few research projects feeds one development project”. Teams in the sidebar (an app-level item — no project needs to be open) is how you do that.

1. Create a team and connect the flows

Create team asks for a name, then drops you into that team’s flow canvas. (The Teams page has two levels: a card list, then the canvas. The list cards show members, flows, and pending counts.)

Add member project picks the projects to manage — when a project joins, Agent NextUp enables its team module automatically, so an “Inbox” appears in its sidebar.

You can switch that module off again at any time in Project settings → Capability modules, including with deliveries still waiting. It puts the Inbox and the delivery tools away without deleting anything — unsent envelopes included — and switching it back on brings all of them back exactly as they were. When deliveries are waiting, the app names how many went quiet with it.

Switching off is not disconnecting. Upstream projects can still route deliveries into this workspace while the module is off — the envelopes arrive in the inbox exactly as they always did; you simply do not see them, and neither does an agent, until the module goes back on. Turn it off to put the surface away, not to stop receiving.

Members are draggable nodes on the canvas (positions are remembered; Tidy up puts everything back in place, and flow lines that span several layers route around intervening nodes rather than being hidden behind them). Each node is a status card: status light, project path, pending count, and when it last received a delivery.

Flows are connected by dragging a line from the connector on a node’s right edge to the left edge of a downstream node. Connections that would create a cycle or duplicate an existing edge won’t drop. The no-cycles rule is per team, and that is also the answer for feedback: when a downstream needs to send work back — bug reports from a product to the library it builds on — create a second team holding just that reverse flow. A project can belong to several teams, and when you route a delivery every downstream across all of them is listed together. Click a connection to select it, then press the Remove edge button that appears on the line.

The canvas pans and zooms (drag empty space, scroll wheel). The left column always lists members (click one to focus its node; hover the row and a remove button appears on the right, which takes the project out of the team after a confirmation — project files are unaffected). A summary bar sits at the top (members / flows / pending / last delivery), and a minimap in the bottom right.

2. Upstream publishes

The upstream project — you, or its agent — presses Publish on the Inbox page and writes a note (what you are delivering, how the downstream should use it). That gets packaged as an envelope in the outbox (on disk, .nextup/exchange/outbox/). For an agent the same move is the publish_delivery hub tool — one of the gatekeeping tools that ship off by default: authorise it on the Tools page first, or the call is refused (and ledgered, like every denied call).

Press Attach files to include actual deliverables (code, reports, images — up to 20 files and 50 MiB total). Selected files appear as removable chips and travel downstream with the delivery. You need at least one of note or attachments — an entirely empty delivery cannot be published.

Files taken from inside the project keep the path they had there, so the downstream sees the same layout your covering note refers to, and two such files may share a name as long as they came from different folders. Files picked from outside the project carry no path — they land under their bare filename, so two outside files with the same name clash and the publish is refused before anything is copied.

Send the contract along with the work. If you are handing over an implementation, attach the specs it was built against as well. A downstream project holding a system but no contract can describe what it sees; it cannot tell you that anything is wrong. Attach the real files rather than copies made for the occasion — every attachment is a snapshot as of the moment you send it either way, but a spare copy sitting in your own project is a second thing to keep up to date, and one of the two will fall behind.

Published something wrong? Publish the correction and mark it as replacing the earlier envelope. In the app, a “Is this correcting an earlier envelope?” picker appears under the attachment row whenever the outbox holds something still correctable; agents do the same through the hub tool. The old envelope is not deleted: it is listed with a Replaced tag so you can see at a glance which one is stale before you press send, and which one actually goes out stays your call. Auto-send skips replaced envelopes entirely — an automatic line has nobody to read the tag, and a delivery cannot be recalled once it lands. Replacing only works while the original is still waiting; once a delivery has been sent, the downstream copy cannot be recalled, so the picker only offers envelopes you have not sent — and not ones you have already marked, since a second correction should point at the envelope that is actually live.

3. You route it (or authorise the line in advance)

Back on the Teams canvas, member nodes with something pending show a numeric badge. Click the node to open the side panel, then press Send on an envelope — a dialog lists every downstream (if a project belongs to several teams, all of their downstreams are listed together, all selected by default). Confirm, and the results are listed one by one.

Flows you trust can have auto-send enabled per edge (a switch on each flow row in the node’s info panel; an All auto checkbox in the header shows and toggles the whole team — empty / indeterminate / checked = all manual / partial / all automatic). Edges with auto-send on are drawn in an accent colour with a ⚡, so you can see at a glance which lines are automatic. From then on, new deliveries on that line are sent automatically with a notification. If the downstream is offline, the first failure tells you and the delivery stays pending for a later retry. If the same delivery still has flows without auto-send, it stays in the outbox until you send those manually.

You still decide how things flow — the only difference is whether you press send per delivery, authorise that line in advance, or put a project in charge of the team (next section). A member’s own agent can only publish; it never routes. Ledger entries are marked so the cases stay apart: (auto) for an automatic line, (by prime <name>) for a coordinator, and nothing for a send you pressed. The coordinator’s mark needs the coordinator to have an identity — NEXTUP_AGENT in its environment — so an anonymous coordinator’s route reads the same as a send you pressed.

Once delivered, the entry moves to the collapsible Delivery history panel at the bottom of the canvas (expanding it shrinks the canvas upward rather than covering the nodes).

4. Downstream picks it up

The delivery appears in the downstream project’s Inbox, labelled with its source and the team it came through. Inside the envelope is the note the upstream wrote, and you can turn it into a task in one click — the note becomes the task’s title and the source reference its description — or record it as a decision, which opens a pre-filled draft you can edit before it enters the ledger.

If the delivery carried attachments, each filename and size is listed below the envelope along with a copyable disk location — copy it and open the files with your own tools. (The inbox does not preview attachments in-app, which preserves the “content is data, not instructions” boundary.)

What the downstream agent sees: no standing pointer. The arrival surfaces to you — a toast, an unread badge, the Inbox row. In an agent’s takeover path it appears only as history: the arrival is a ledger event, so the handoff snapshot (regenerated the moment a delivery lands) shows a DeliveryReceived line in its recent-activity window until later events push it out. Beyond that transient line there is nothing: the AGENTS.md state block carries no delivery lines, and no protocol step says “check for deliveries”. An agent can read the inbox — the read tools list_deliveries and get_delivery come with the module, and the team module guide the workspace ships covers them — but no standing prompt sends it there. Walking a delivery into the project’s plan is a human move: turn it into a task, or point your agent at the envelope yourself.

Letting one project run the team

Once a team has more than a couple of members, routing every delivery and redrawing flows by hand gets repetitive. You can hand that job to a project: press Coordinator in the team header and pick one. Its agent can then read every member’s status, edit the flows, route deliveries, and change the roster — bringing a project in, creating a new one to bring in, or taking one out. That is the work you would otherwise be doing on this canvas.

A coordinator is not a member of the team it runs. It sits above the flow the canvas draws, so it has no node there and no delivery edges, and the member list it reads never includes itself. A project holds one seat per team: you cannot name a member as coordinator, and you cannot add the coordinator as a member. That is also why it needs no edge to hand work down — it can already see every member, and edges exist to move things between projects that cannot see each other.

Naming a coordinator switches on that project’s Team coordination (prime) capability module for you — a coordinator whose module is off would be a badge with no tools behind it.

Naming is itself the grant — for the overview, and only the overview. From the moment you name it, the coordinator can see each member’s summary: phase, task counts, mailbox counts, and the first line of each envelope. That is deliberate. Naming a project as coordinator is the human act of putting it in charge, and a coordinator that cannot see who is busy has been put in charge of nothing.

Everything past the overview waits for you. Reading inside a member, editing the graph, routing, and the sign-off below are each off until you authorise them on that project’s Tools page, one at a time. And a coordinator has no way to give itself any of this: naming one is a human action with no tool behind it, and the naming is also what scopes the authority — to this team, not to every team on the machine.

A coordinator can see what you can see. Task text, decisions, progress notes, the current-state specs — the same material you would read by opening that project yourself. These deeper reads are never silent: each one is written into that member’s own ledger, saying which coordinator did it, so a project can always find out it was read. The summary reads above are the exception — they are counts, they run across every member at once, and they leave no line.

What it cannot do is the work. It never creates a task in another project, changes a status, advances a phase, marks someone’s work verified or confirms a gate you were meant to confirm. Each member has its own gates, its own ledger and its own permissions you granted it; work happens in a project because that project’s agent does it, under those. So a coordinator’s way of getting something done elsewhere is to deliver the material and have someone work there — not to reach in.

The one exception is sign-off: a coordinator can archive a member’s finished task, which is also what folds that task’s spec deltas into that project’s specification. That is the approval step you would otherwise press, and it is a separate permission from reading. It is approval rather than substitution — a task carrying spec deltas is refused until that member’s own agent has verified it.

Two other coordinator actions do touch a member’s folder, though neither is its work: joining a project to a team switches the team module on there, which rewrites that project’s state block and ships it the module’s guide; and routing a delivery writes the envelope into the recipient’s inbox and appends the arrival to its ledger. Both are the same writes the app performs when you press the buttons yourself.

Authority is per team. A project can coordinate one team and be an ordinary member of another, and switching the coordinator off is instant and loses nothing.

Maintenance

If a member project’s folder moves, or its disk isn’t attached, the node turns dashed and is marked missing — open its info panel and press Re-link folder to point it at the new location. Matching is by stable id, so picking the wrong folder is rejected.

Removing a member leaves the coordinator alone — it was never one of them. Handing the job to a different project, or clearing it entirely, is the Coordinator button in the team header.