squad

• **One captain, multiple members. ** The leader must be an agent; members can be agents or human members. Teams with only one leader are also allowed (the captain's briefing will indicate "no other members"), and the same agent can also join multiple teams.
• **Squads can be selected anywhere where people can be selected. ** Assignee picker, @mention picker, quick creation modal - the squad will appear wherever an agent or member's position can be selected.
• **Delete via "Archive" soft delete. ** After archiving a team, it will disappear from the picker and list; the issue currently assigned to it will be ** automatically transferred to the team leader agent ** so that the work will not get stuck. Archived teams cannot be assigned new issues.

Scenario using a team	Scenario using a single agent
There are several experts, but I don’t know who should own this issue in advance	The scope of work is very clear, and I know who should do it
I want the assignee (team) to be stable, and the actual responder changes according to the issue	I hope the name of the agent is listed on the issue, and the responsibilities are clear
Want a routing target like @FrontendTeam	One-to-one @agent-name is enough

Operation	Who can do it
Create/Update/Archive Team	Workspace owner or admin
Add, delete members, change member roles	Workspace owner or admin
Assign the issue to the team	Any workspace member (same as assigning to the agent)
In comments @ Team	Any workspace member
Record the evaluation of the team leader	Only the leader agent himself (via CLI)

• Name - For example Frontend Team, Bug Triage. There is no requirement to be unique in the workspace.
• Description (optional) - a one-sentence introduction, displayed on squad cards and details pages.
• Leader - Select an existing agent. After creation, the captain will automatically join the team as leader role.

After creating, open the team details page to:

• Add members - Select agents or human members; you can add a "role description" to each member (such as "owns the migrations", "reviewer of last resort"). The captain will refer to these characters when assigning tasks.
• Write instructions - Squad level instructions, visible to the leader every time they are executed (see below).
• Set Avatar - Use the same avatar selector as the agent.

CLI equivalent command:

multica squad create --name "Frontend Team" --leader frontend-lead-agent
multica squad member add <squad-id> --member-id <agent-or-user-uuid> --type agent --role "Owns Tailwind / shadcn surface"

1. **The captain takes away the task. ** The daemon where the captain is located will take away the task in the next poll, which is the same as the allocation process of ordinary agents.
2. **The captain gets the briefing. ** At the moment of being taken away, Multica will append three paragraphs of content after the captain's system prompt - see below for details [What the captain sees every time he executes](#What the captain sees every time he executes).
3. **The captain posted a "distribution" comment. ** In the comments, use the mention markdown @ given in the roster for the selected member - this @ will trigger the assigned member to join the team for a new task.
4. Captain record evaluation: multica squad activity <issue-id> action --reason "...". This line will be written into the issue's activity timeline, making it easier for humans to trace back that the captain has indeed evaluated this trigger.
5. **The captain stopped. **After the work is assigned, the captain does not start the work. When the dispatched member responds, the captain will be automatically awakened to decide the next step: continue dispatching, throw it to humans, or remain silent.

If the issue is in the Backlog state, the captain will not be triggered - the Backlog is the parking lot, and the rules are the same as directly assigned to the agent.

What the captain sees every time he executes

Each time a captain is triggered, three pieces of content are appended to its instructions:

• Squad Operating Protocol - A hard-coded set of rules: read the issue → use @ to assign tasks → be concise (don’t repeat the content of the issue, the assigned members can read it themselves) → record the evaluation every time → stop after dispatching. This section is managed by the system and cannot be edited.
• Squad Roster - one row for the captain + one row for each unfiled member. Bring exactly available mention markdown ([@Name](mention://agent/<uuid>) or [@Name](mention://member/<uuid>)) on each line for the captain to copy directly - plain text @name will not trigger anyone.
• Squad Instructions - Private items you write for this squad (edit in the details page, or use multica squad update --instructions). Used to write routing rules ("DB-related dispatch to Alice, front-end dispatch to Bob"), reporting strategies, or any background that the issue itself will not have.

Event	Trigger Captain?
Comments from non-team members (human reporters, external agents)	Meeting
Team members send "progress updates" without any** @mention	Meeting - the team leader re-evaluates whether the next step is needed
In comments posted by anyone, explicit @ Agent / Member / Team / @all	No - Explicit @ is the routing signal, and the captain gives up
Comments posted by the captain himself	No - hard-coded to prevent self-triggering
There are only issue links in the comments [MUL-123](mention://issue/...)	Yes——issue references are not counted as routes

On top of the above rules, there is also deduplication: if the leader already has a queued or dispatched task on this issue, the new trigger will not re-enter the queue.

**Why @ comments posted by members do not wake up the captain. ** Once a team member directly @ someone, that comment is a conscious handover - asking the captain to wake up the "observation" route again will only produce an empty round and mess up the timeline. The exception is the agent author's comment: when an agent emits a result and @s another agent, the captain is still awakened in order to coordinate the entire thread.

The same anti-loop rules apply: the captain skips himself; if a member is also explicitly marked with @ in the same comment, the route will fall directly to that member.

Archive squad (multica squad delete <id>, or the Archive button on the details page):

1. The issue currently assigned to this team will be automatically transferred to the captain agent, so that the work falls on a specific agent to avoid no one taking over.
2. Write archived_at / archived_by on the squad table - the record is retained, and the historical activities can still be parsed; but it disappears from the list, picker, and @ drop-down list.
3. Reject subsequent assignment - cannot assign to an archived squad.

There is currently no "unarchive" command; to restore routing, just create a new team.

Command	Purpose
multica squad list	List the squads in the workspace
multica squad get <id>	View the squad name, captain, description, instructions
multica squad create --name "..." --leader <agent>	Create a squad (owner/admin)
multica squad update <id> [--name X] [--description X] [--instructions X] [--leader Y] [--avatar-url Z]	Modify one or more fields
multica squad delete <id>	Archive (soft delete) - and transfer the issue currently assigned to the squad to the captain
multica squad member list <id>	List squad members
multica squad member add <id> --member-id <uuid> --type agent|member [--role "..."]	Add member (owner/admin)
multica squad member set-role <id> --member-id <uuid> --member-type agent|member --role "..."	Modify the role directly without removing the member
multica squad member remove <id> --member-id <uuid> --type agent|member	Remove members (cannot remove captain - change captain first)
multica squad activity <issue-id> <action|no_action|failed> --reason "..."	The captain is called by itself before each end

• Assign issues to agents - The process is the same, and it also applies to the team assignee
• @ agents in comments - @ picker can also select teams
• Agents - "parts" of the team
• Members and Permissions - complete permission comparison of owner / admin / member