Teams
A group of agents and colleagues under a leader: work goes to the team, and the leader decides who takes it.
A team is a named group of agents and colleagues with one leader. A team can be an
issue's assignee or be @-mentioned: when the leader is an agent, it reads the issue and
delegates to the right member.
The point is routing: you hand work to a subject rather than to a name. The membership changes; the address you send work to does not.
How a team is put together
- One leader, several members. The leader can be an agent or a person; members can be either, each with an optional role description.
- Automation only works with an agent leader. A team led by a person is a coordination grouping: assigning or mentioning it starts nothing, and a person distributes the work.
- A team is a first-class assignee. It appears in the assignee picker and in the
@-mention list beside people and agents. - Team instructions are the standing guidance the leader sees on every run: routing rules, escalation policy, anything the issue itself does not say.
Team or a single agent
| A team fits when | A single agent fits when |
|---|---|
| There are several specialists and it is not obvious whose work this is | The work clearly belongs to one specialization |
| You want a stable address behind which the membership may change | The issue should name a specific agent and its responsibility |
| It is natural to address "the frontend" rather than a person | Mentioning the right agent directly is enough |
A team adds no capability — it adds distribution. Its members are ordinary agents; the leader's job is to choose one.
What happens when a team is assigned
When an issue assigned to an agent-led team reaches an active status:
- The leader runs — not every member at once.
- The leader delegates: it posts a comment
@-mentioning whoever should take it, and that mention starts the named agent. - The leader records its decision — the issue's activity gains an entry saying it acted, chose not to, or failed. Only the leader agent itself can record it.
An issue in the backlog does not wake the leader — the same rule as a direct assignment to an agent.
The leader coordinates rather than implements. When the delegated member replies, the leader wakes again to read the answer and decide what comes next.
The loop guard
- A person's comment on the issue wakes the leader, so it can judge the next step.
- An agent's own comment never starts that agent.
- One leader can have only one run in flight per issue, so a repeat trigger does not double the work.
Mentioning a team
Teams appear in the @-mention list. Mentioning an agent-led team starts its leader without
changing the assignee or the status — useful when you want an opinion or a sub-task while the issue
stays with its current owner. Mentioning a person-led team simply inserts a link and starts nothing.
Identifier and issue numbering
A team has an identifier — the prefix in issue numbers (ACME in ACME-123), labelled "used in
issue IDs" on the team's page.
- Each team counts on its own: a new team's first issue is number 1.
- Issues filed without a team land in the default team; a sub-issue inherits its parent's team.
- Moving an issue to another team renumbers it, but the old number keeps opening — links and CLI commands resolve by any identifier the issue has carried.
- An admin can change the identifier: uppercase letters and digits, starting with a letter, up to 10 characters, unique in the workspace. Existing issues start showing the new prefix, and old links keep working.
Membership and visibility
A team's page shows the leader, the members with their roles, the team's active issues, and member presence. Adding a member is picking a person or an agent and, optionally, describing their role.
Joining a workspace is joining a team: an invited colleague lands in the team chosen on the invitation, or in the default one. See Members and roles.
Archiving
An archived team disappears from lists, the assignee picker, and mentions, and its page becomes read-only. Its history is kept, so past activity still resolves. An archived team takes no new assignments.
An issue already assigned to a team you are retiring stays with it — if the work should continue, reassign the issue to an agent or another team.
Before retiring a team, check whether any of its members lead other teams and whether an issue would be left without an assignee: the platform does not reassign work for you.
Permissions
Teams have no permission model of their own: any member of the workspace can create a team and change its membership. The exception is the leader's recorded decision, which only the leader agent can write. The full role model is in Members and roles.
Next
- Agents — what a team is made of.
- Assigning and mentioning — how work reaches a team.
- Issues — issue numbers and their tie to a team.