Multica Squads

Multica Squads

Quick start

If debugging why a squad did or did not run, inspect first:

multica issue get <issue-id> --output json
multica squad get <squad-id> --output json
multica squad member list <squad-id> --output json
multica issue comment list <issue-id> --recent 20 --output json

If the command shape is unclear, check help instead of guessing:

multica squad --help
multica squad member --help
multica issue update --help
multica issue comment add --help

Do not assign, comment, mention, update, delete, or record squad activity just to test. These can mutate workspace state or trigger agent runs.

Core model

A Multica squad is a workspace routing and coordination object.

A squad is not an agent. It does not run work by itself. Current behavior: squad-routed work runs through the squad's leader_id agent.

Important consequences:

• assigning an issue to a squad routes to the leader;
• mentioning a squad routes to the leader;
• squad-assigned autopilot resolves to the leader;
• squad members are not automatically fanned out;
• squad instructions are leader briefing content, not member prompts.

CLI

Squad commands:

multica squad list --output json
multica squad get <squad-id> --output json
multica squad create --name <name> --leader <agent-name-or-id> --output json
multica squad update <squad-id> --instructions "<leader coordination policy>" --output json
multica squad delete <squad-id>

Member commands:

multica squad member list <squad-id> --output json
multica squad member add <squad-id> --member-id <id> --type agent|member --role <role> --output json
multica squad member remove <squad-id> --member-id <id> --type agent|member
multica squad member set-role <squad-id> --member-id <id> --member-type agent|member --role <role> --output json

Squad leader evaluation command:

multica squad activity <issue-id> action|no_action|failed --reason "<why>" --output json

activity is a write: it records the leader's evaluation decision on an issue. Use it only when acting as the squad leader after evaluating a trigger.

Issue/comment commands often needed with squads:

multica issue get <issue-id> --output json
multica issue update <issue-id> --help
multica issue comment list <issue-id> --output json
multica issue comment add <issue-id> --help

Prefer --output json for reads. Use --help before writes.

Squad fields

• id — squad UUID.
• workspace_id — workspace the squad belongs to.
• name — display name; unique per workspace.
• description — human-facing metadata/display text. Do not assume runtime

prompt impact unless source proves a consumer.

• instructions — squad-level instructions added to the squad leader briefing.

They are not directly injected into every squad member.

• avatar_url — optional squad avatar URL.
• leader_id — agent ID of the squad leader; the runtime target for

squad-routed work.

• creator_id — creator of the squad.
• archived_at / archived_by — archive metadata. Archived squads are rejected

by assignment/autopilot routing paths.

• member_count — list response count of squad members.
• member_preview — list response preview of squad members.

Use instructions for leader-facing coordination policy: squad responsibility, delegation expectations, when to ask humans, and review/handoff rules. Do not write it as if every member automatically receives it.

Squad member fields

• member_type — agent or member.
• member_id — ID of the agent or workspace member.
• role — roster role label. Current behavior: non-empty role appears in the

leader briefing roster. Do not assume it creates scheduling, permissions, or routing behavior.

Creation and leader membership

Creating a squad requires leader_id. The leader must be a workspace agent. Create/update does not reject an archived leader: the lookup only checks the agent exists in the workspace. An archived leader fails closed later, at routing/dispatch — assignment, autopilot admission, and the comment/mention readiness gate all reject an archived leader before any task is enqueued.

On create, the backend attempts to add the leader as a squad member with role leader. When updating leader_id, if the new leader is not already a member, the backend adds the new leader as a squad member with role leader.

Leader briefing

For squad leader tasks, Multica appends a squad leader briefing to the leader agent instructions. The briefing includes:

• Squad Operating Protocol;
• Squad Roster;
• Squad Instructions, only when instructions is non-empty.

Roster entries include member name, member type, mention markdown, and non-empty role. Archived agent members are skipped from the briefing roster.

Issue assignment behavior

Issues can be assigned to squads with:

assignee_type = "squad"
assignee_id = <squad-id>

Current behavior:

• assignment routes work to squad.leader_id;
• it does not enqueue every squad member;
• assignment while status is backlog does not immediately start work;
• moving a squad-assigned issue out of backlog can trigger the leader;
• changing assignee cancels existing tasks for the issue before enqueueing the

new assignee path.

Assignment validation rejects a missing type/id pair, non-existent squad, archived squad, archived leader, and private leader when the actor cannot access it.

Comment and mention behavior

If an issue is assigned to a squad, a new comment can wake the squad leader. This is leader routing, not member fan-out.

Squad mention format:

[@Squad Name](mention://squad/<squad-id>)

Current behavior: resolve the squad, read leader_id, enqueue a leader task, and use the current comment as the trigger comment. It does not enqueue every squad member.

Autopilot behavior

Autopilots can be assigned to squads. For assignee_type = "squad":

• executable agent resolves from squad.leader_id;
• admission/readiness checks run against the leader;
• archived squads fail closed / skip dispatch;
• run attribution records squad id where applicable.

For create_issue autopilots, the created issue keeps assignee_type = "squad" and assignee_id = <squad-id>, while the actual executing agent is the resolved leader. For run_only autopilots, no issue is created; the task is created directly for the resolved leader agent.

Handling complaints or product gaps

When the user says squad behavior is wrong, confusing, or disappointing, do not immediately assume code is broken and do not defend current behavior just because it exists. Classify first:

• expected current behavior;
• configuration issue;
• product limitation;
• actual bug.

Explain the current source-backed behavior. If the behavior is technically correct but product-wise bad, say so and propose a scoped product/code change.

Do not silently change squad routing, member fan-out, leader briefing, autopilot behavior, or comment-trigger behavior without confirmation. These are product contract changes with side effects.

Side effects

These actions can trigger agent work or mutate durable state:

• creating a squad;
• updating squad fields;
• changing leader_id;
• adding/removing members;
• changing member roles;
• assigning an issue to a squad;
• moving a squad-assigned issue out of backlog;
• commenting on a squad-assigned issue;
• mentioning a squad;
• creating or triggering squad-assigned autopilots;
• recording squad activity with multica squad activity;
• deleting/archive squad.

Do not perform side-effecting actions as tests unless the user explicitly authorizes them.

Common wrong assumptions

• A squad is not an agent.
• Squad work routes to leader_id, not every member.
• Squad mention routes to the leader, not every member.
• Squad assignment routes to the leader, not every member.
• Squad autopilot resolves to the leader as executable agent.
• instructions are leader briefing content, not automatic member prompts.
• description is not proven runtime prompt content.
• role is roster context, not automatic scheduling.
• Backlog assignment does not immediately start work.

References

For source paths, tests, edge cases, and exact routing details, see:

references/squad-source-map.md

Squad Source Map

This file records source evidence for multica-squads/SKILL.md.

Use this when the task requires exact source paths, edge-case behavior, tests, or contract verification.

Object Model

DB shape

Source:

server/migrations/084_squad.up.sql                # base table: name, description, leader_id, creator_id
server/migrations/085_squad_archive.up.sql        # archived_at, archived_by columns
server/migrations/088_squad_instructions.up.sql   # instructions column
server/pkg/db/queries/squad.sql
packages/core/types/squad.ts

Key facts:

• squad stores name, description, leader_id, creator_id (084), archive

metadata archived_at/archived_by (085), and instructions (088).

• squad_member stores member_type, member_id, and role.
• member_type is constrained to agent or member.
• issue assignee_type supports squad.

CLI

Source:

server/cmd/multica/cmd_squad.go

Commands:

multica squad list
multica squad get <squad-id>
multica squad create
multica squad update <squad-id>
multica squad delete <squad-id>
multica squad activity <issue-id> <outcome>

multica squad member list <squad-id>
multica squad member add <squad-id>
multica squad member remove <squad-id>
multica squad member set-role <squad-id>

Use --help for exact flags before writes.

Create / Update

Source:

server/internal/handler/squad.go                  # CreateSquad ~200-272, UpdateSquad ~287-364
server/pkg/db/queries/agent.sql                   # GetAgentInWorkspace ~15-17
server/pkg/db/generated/agent.sql.go              # getAgentInWorkspace ~1261

Contracts:

• create requires leader_id (squad.go:215-218);
• leader must be a workspace agent — both create (squad.go:230-237) and update

(squad.go:333-338) validate via GetAgentInWorkspace;

• archived leader is NOT rejected at create/update: GetAgentInWorkspace is

WHERE id = $1 AND workspace_id = $2 (agent.sql:15-17) with no archived filter, so an archived agent can be set as leader here. Archived-leader fails closed later, at routing/dispatch — see the readiness gate (squad.go:945, isSquadLeaderReady → service.AgentReadiness at squad.go:1017), assignment validation (issue.go:2625-2627), and autopilot admission (autopilot.go:885-891);

• leader is auto-added as member with role leader (squad.go:258-263);
• updating leader_id auto-adds new leader as member if missing (squad.go:340-347).

Leader Briefing

Source:

server/internal/handler/squad_briefing.go         # buildSquadLeaderBriefing ~104, buildSquadRoster ~121, renderMemberRow ~169
server/internal/handler/daemon.go                  # briefing injection ~1187, ~1530

Contracts:

• squad leader tasks append briefing to leader agent instructions

(daemon.go:1187, 1530);

• briefing includes operating protocol, roster, and optional instructions

(squad_briefing.go:104-117);

• instructions section appears only when non-empty (squad_briefing.go:110-112);
• archived agent members are skipped from roster (squad_briefing.go:178-179);
• no traced behavior injects instructions into every squad member.

Issue Assignment

Source:

server/internal/handler/issue.go                  # assignee validation ~2614-2632
server/internal/handler/squad.go                   # shouldEnqueueSquadLeaderOnAssign ~990, enqueueSquadLeaderTask ~1027
server/internal/service/task.go

Contracts:

• assignee_type="squad" routes to squad.leader_id (squad.go:1028-1050);
• backlog assignment does not immediately enqueue (squad.go:991-993);
• moving out of backlog can enqueue leader (squad.go:990-994 → isSquadLeaderReady);
• assignee change cancels existing issue tasks first;
• private leader access is checked at assign-time (issue.go:2629-2632) and at

enqueue-time via canEnqueueSquadLeader (squad.go:1037);

• archived squad / archived leader rejected at assign-time (issue.go:2622-2627);
• pending task dedup is applied (squad.go:1042-1048).

Comment / Mention

Source:

server/internal/handler/comment.go                # comment triggers ~1057-1199, squad mention branch ~1352
server/internal/handler/squad.go                   # enqueueSquadLeaderTask ~986 (assign/backlog paths), lastTaskWasLeader ~915
server/internal/service/task.go                   # EnqueueTaskForSquadLeader

Contracts:

• commenting on a squad-assigned issue can wake the leader — the comment path

computes triggers via computeCommentAgentTriggers (comment.go:1124), whose assigned-squad branch is computeAssignedSquadLeaderCommentTrigger (comment.go:1162-1199); the same computation backs the trigger-preview endpoint;

• explicit mention://squad/<id> resolves squad and adds the leader trigger

(comment.go:1352-1391);

• squad mention does not fan out to members — enqueue targets squad.LeaderID

only (comment.go:1104-1112, and squad.go:1007 on the assign/backlog paths);

• leader task uses is_leader_task=true (via EnqueueTaskForSquadLeader);
• leader self-trigger loops are guarded — same-leader / last-task-was-leader

guards (comment.go:1173-1176, lastTaskWasLeader at squad.go:915) and member explicit-mention skip (comment.go:1177-1179).

Autopilot

Source:

server/internal/service/autopilot.go              # resolveAutopilotLeader ~617-655, dispatch ~88-111
server/internal/handler/autopilot.go              # save-time validateAutopilotAssignee ~845-893

Contracts:

• squad autopilot resolves executable agent from squad.leader_id —

resolveAutopilotLeader squad branch (autopilot.go:639-651);

• readiness/admission checks target the leader: save-time validation rejects an

archived squad/leader (handler/autopilot.go:881-891), and dispatch re-runs resolveAutopilotLeader + AgentReadiness;

• archived squad fails closed / skips dispatch — errSquadArchived

(autopilot.go:644-645);

• create_issue keeps the issue assigned to the squad (autopilot.go:88-97);
• run_only creates task directly for leader (autopilot.go:99-106, dispatch via

resolveAutopilotLeader at autopilot.go:284).

Child-done Parent Trigger

Source:

server/internal/handler/issue_child_done.go       # dispatchParentAssigneeTrigger ~246, triggerChildDoneSquad ~304

Contracts:

• when child issue completes and parent is assigned to squad, parent squad

leader can be triggered (triggerChildDoneSquad at issue_child_done.go:304);

• routing is leader-only — one EnqueueTaskForSquadLeader on the leader, no

member fan-out (issue_child_done.go:214-216, 344);

• loop guards skip same squad, same effective leader, and shared-leader

cross-squad cases (issue_child_done.go:229-235, effectiveChildAgentOwner ~367, childAssigneeIsSquad ~387).

Private Leader Access

Source:

server/internal/handler/agent_access.go           # canAccessPrivateAgent ~25-40, canEnqueueSquadLeader ~82-91
server/internal/handler/squad.go                   # enqueueSquadLeaderTask gate ~1037

Contracts:

• public leaders pass — canAccessPrivateAgent returns true when

agent.Visibility != "private" (agent_access.go:26-28);

• agent-to-agent traffic is allowed — actorType == "agent" short-circuits

(agent_access.go:29-31);

• private leader access for members is limited to owner/admin or agent owner

(agent_access.go:32-39);

• system triggers are treated like agent triggers for squad leader enqueue:

canEnqueueSquadLeader remaps actorType == "system" to "agent" before delegating to canAccessPrivateAgent (agent_access.go:87-90). This is wired into enqueueSquadLeaderTask, which denies the enqueue when the actor cannot access the leader (squad.go:1037).

Tests

Relevant test groups:

server/internal/handler/squad_assign_trigger_test.go
server/internal/handler/squad_comment_trigger_test.go
server/internal/handler/squad_briefing_test.go
server/internal/handler/squad_private_leader_test.go
server/internal/handler/autopilot_private_leader_test.go
server/internal/handler/squad_no_action_test.go

Verification command:

go test ./internal/handler -run 'Test.*Squad|Test.*squad|Test.*Autopilot.*Squad|Test.*ChildDone.*Squad'