multica-squads

Stars42,079

Forks5,331

UpdatedJuly 22, 2026 at 12:33

Use when creating, inspecting, updating, assigning, mentioning, or debugging Multica squads. Explains what squads are, squad/member fields, CLI commands, leader routing, issue assignment, comments, mentions, autopilot behavior, leader briefing, side effects, and product-gap handling.

Installation

Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.

Source

multica-ai

multica-ai/multica

View GitHub Repository View Creator Repositories

Download

Related occupationsSOC

Based on SOC occupation classification

Computer Occupations, All OtherComputer and Mathematical Occupations·SOC 15-1299

File Explorer

2 files

SKILL.md

readonly

More from this repository

same repository

multica-working-on-issues

multica-ai/multica

Use when working on a Multica issue after the runtime has provided the trigger context — to apply the product contracts the runtime brief does not encode: how PR linking differs from close intent, how to read a linked PR's real state via the pull-requests CLI, which metadata keys are high-signal, what status changes trigger on the server, and how sub-issue create status (todo vs backlog) controls whether assigned agents start immediately.

2026-07-2442.1k

multica-creating-agents

multica-ai/multica

Use when creating, inspecting, or debugging a Multica agent through the `multica agent` CLI or `POST /api/agents` — what each field is, its persisted shape, whether it is metadata-only or consumed by the daemon at claim time, which inputs are validated/rejected, how custom_env secrets are gated, and how skill binding behaves. Not for assigning issues to existing agents or for runtime task prompts.

2026-07-2342.1k

multica-runtimes-and-repos

multica-ai/multica

Use when inspecting or debugging Multica runtimes, daemon task claiming, agent not running, workdir/session reuse, or repository checkout. Covers runtime online/offline state, daemon heartbeat/claim chain, task-scoped repo checkout, project repo context, local_directory caveats, and safe diagnostic commands.

2026-07-2242.1k

multica-skill-importing

multica-ai/multica

Use when a user provides a skill URL, slug, or clear intent to import/install a specific skill into the current Multica workspace. Teaches the workspace import API/CLI path (POST /api/skills/import), the supported URL source families, --on-conflict fail|overwrite|rename|skip behavior and structured import results, additive agent binding vs replace-all, and the reserved SKILL.md supporting-file rule. Do not use it to decide which skill the user needs, and never treat an external local installer like npx skills add as the final Multica install.

2026-07-2242.1k

multica-autopilots

multica-ai/multica

Use when creating, updating, inspecting, triggering, or debugging Multica autopilots. Covers the full chain: schedule/webhook/manual trigger, create_issue vs run_only execution, agent/squad leader admission, runs, created issues/tasks, webhook URL rotation, and side-effect boundaries.

2026-07-1742.1k

multica-mentioning

multica-ai/multica

Use when an issue comment needs to @mention someone — link to a person, trigger another agent, hand work to a squad, or broadcast with @all. Documents the verified mention contract: how a mention link is built from a real UUID, the four mention types and exactly what each one enqueues (agent → a run for that agent, squad → a run for the squad leader, member and issue → a rendered link with NO run), comment create/edit preview and suppression, the @all broadcast and how it suppresses the assignee's auto-trigger, and the silent no-op cases (a name where a UUID belongs, a bad/unknown UUID, an already-pending task, an archived agent, a private agent you cannot access). WHETHER to mention — loop avoidance, staying silent on acknowledgements — lives in the runtime brief's Mentions section, not here. This skill is the backend contract only, traced to server/internal/util/mention.go and server/internal/handler/comment.go.

2026-07-1642.1k

name	multica-squads
description	Use when creating, inspecting, updating, assigning, mentioning, or debugging Multica squads. Explains what squads are, squad/member fields, CLI commands, leader routing, issue assignment, comments, mentions, autopilot behavior, leader briefing, side effects, and product-gap handling.
user-invocable	false
allowed-tools	Bash(multica *)

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 10 --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. For agent members the roster also lists their assigned skills (skills: a, b, or no skills assigned when the agent has none) so the leader can delegate by capability instead of guessing from the role label; human members carry no skills segment. Builtin multica-* skills are not listed — only the workspace skills explicitly attached to the agent. 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;
parent issue status is agent-managed (same model as direct agent assignment): the leader's first assignment turn should move the parent to in_progress and keep it there while members work; the leader moves the parent to in_review only when a later re-trigger confirms the overall goal is met. Completing a leader task (including the first dispatch) does not itself change issue status;
that status authority is granted only when the issue's assignee_type / assignee_id point at THIS squad. The leader briefing is injected on every leader path, including an @squad mention on an issue owned by a plain agent — on those paths the protocol instead carries an explicit "do not change this issue's status".

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.
First leader dispatch is not parent completion — parent stays in_progress until the leader later confirms the overall goal and moves it to in_review.
The server does not auto-flip parent status when child issues finish; it only wakes the leader with an explicit ask (including in_review when wrapping up).
Getting the leader briefing does NOT imply status authority. A squad @-mentioned into an issue assigned to someone else is a guest: roster and delegation rules yes, multica issue status no.

References

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

references/squad-source-map.md