Teams & workflow

Anatomy of a team

Your workspace's team has three pieces:

• Teammates — the specialists you create. Each one has its own folder, its own conversation, its own running tools. You author the spec; the platform stands the Teammate up in the workspace and gives it a name (the agent key).
• The Manager — auto-created when you have two or more Teammates. It's the front door: every message you send to the team arrives at the Manager first. It either answers directly or hands the request to whichever Teammate is the right fit, then synthesizes the reply.
• The shared workspace — one persistent filesystem visible to every Teammate and the Manager. When one Teammate writes a file, the others can read it on their next turn. This is the substrate the team collaborates on.

You don't configure the Manager or the workspace yourself — they appear once your team meets the threshold. What you control is the Teammates.

How the Manager routes work

When you send a message to the team, the Manager reads it and decides between three actions:

1. Answer directly. For simple questions, summaries, status checks, or anything not specialist-shaped, the Manager replies itself. No hand-off needed.
2. Delegate to one Teammate. Picks the Teammate whose role best matches the request, hands it off with the necessary context, waits for the reply, then synthesizes it back to you.
3. Sequence a few Teammates. When the work spans roles (research → draft, or analyse → recommend), the Manager hands off to the first, takes the result, and feeds it into the next.

The Manager picks based on what each Teammate's spec describes about its role. Clear, scoped role descriptions in each AGENT.md are how you steer routing.

Sharing state through the workspace

The shared filesystem is the team's collaboration medium. Patterns that work well:

• Conventional folders. Agree on a layout — ~/research/, ~/drafts/, ~/repos/, ~/notes/<teammate-name>/ — and put it in each Teammate's AGENT.md. The Manager benefits from knowing the layout too.
• Filename hand-offs. When a Teammate produces output another will consume, write it to a predictable path and tell the Manager you've done so. The Manager then tells the next Teammate where to read.
• Long-lived artifacts. Cloned git repos, build caches, installed CLIs all live in the workspace and survive from one conversation to the next. Set them up once; reuse forever.
• Per-Teammate scratch. Each Teammate's own folder (~/Agents/<agent-key>/) is its private space for notes, in-flight drafts, and intermediate state — visible to others but conventionally that Teammate's territory.

The platform doesn't enforce any of these conventions. They're guidance for keeping a multi-Teammate workspace coherent.

Designing Teammates that compose

A team is more than the sum of its Teammates if the specs are written to collaborate. A few principles:

• One role per Teammate. Code reviewer, researcher, content writer, data analyst — narrow, named, easy to route to. Avoid "general-purpose" Teammates; the Manager has nothing to route on.
• State what you produce. Each spec should say "I write outputs to ~/drafts/" or "I post results back as a reply." Tells the Manager and the team what to expect.
• State what you consume. "I read source materials from ~/research/." Lets the Manager set up the hand-off cleanly.
• Avoid overlapping responsibilities. Two Teammates that both claim "I do research" is a routing ambiguity. Pick one to own it; the other defers.
• Keep the Manager out of execution. The Manager coordinates; it shouldn't be doing specialist work itself. If you find the Manager doing a Teammate's job, it's a sign that Teammate's role is unclear in its spec.

Adding and removing Teammates

Create a new Teammate the same way as any agent — author the spec, push it, configure it. As soon as you do, the new Teammate appears in the workspace with its own folder and tmux session; the Manager starts routing to it on the next turn that needs its role.

Removing a Teammate retires the agent but preserves the workspace files it produced. The Manager stops routing to it; the rest of the team is unaffected. Anything that Teammate wrote to the shared workspace stays where it was — other Teammates can still read those files.

Going from two Teammates back down to one removes the Manager (it's auto-created at the threshold, and auto-retired when the threshold no longer holds). The remaining Teammate becomes your direct point of contact.

Lifecycle reminder — Teammates aren't deployed

There's no deployToTest / deployToProd step for a Teammate. There's no test URL, no prod URL, no embed snippet, no custom domain. A Teammate's lifecycle is simpler: author the spec → push it → configure → the Teammate lives in your workspace from then on. Updating its instructions or skills re-pushes the spec; the Teammate keeps its workspace and conversation continuity.

All the publishing apparatus that lives in Deploy & Embed is for Freelancers only.