multica-mentioning

name: multica-mentioning description: "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." user-invocable: false allowed-tools: Bash(multica *)

Mentioning & Delegating

This skill states WHAT a mention link does in the Multica backend, traced to source. WHETHER to mention at all — loop avoidance, staying silent on acknowledgements — is in your runtime brief's Mentions section; follow that and do not repeat it here.

Every claim below is pinned to source in references/mentioning-source-map.md. If behavior ever differs from this document, the source map is where to re-check it.

A mention link is built from a real UUID

The backend recognizes a mention only through this Markdown shape:

[@Label](mention://<type>/<id>)

The parser (util.MentionRe in server/internal/util/mention.go) accepts exactly four <type> values plus the all sentinel, and the <id> group accepts only hex characters and dashes, OR the literal string all:

(member|agent|squad|issue|all)/([0-9a-fA-F-]+|all)

So the link target is a real entity UUID (or all), never a display name. The label between the brackets is free text — that is where the human-readable name goes.

Step 1 — look up the UUID with --output json

A name is not a UUID. Look the UUID up first, from the matching list command:

• a person → multica workspace member list --output json → use user_id
• an agent → multica agent list --output json → use id
• a squad → multica squad list --output json → use id

For a person the mention id is the user_id, NOT the membership-row id — the backend's own roster formatter uses user_id for member mentions. Match by display name. If the name is ambiguous or absent, do not guess — say so in your comment instead of emitting a broken link.

Step 2 — the four types and exactly what each enqueues

Format: [@Name](mention://<type>/<uuid>). The <type> and the id source must match, or the link resolves to the wrong entity (or to nothing).

The mention trigger set is computed by computeMentionedAgentCommentTriggers (server/internal/handler/comment.go); the comment path folds that result into computeCommentAgentTriggers and enqueues it via enqueueCommentAgentTriggers. It acts on two types only: the squad branch resolves the squad and adds its leader to the trigger set; everything that is not agent after that is skipped (if m.Type != "agent" { continue }), then the agent branch adds that agent. A member or issue mention reaches neither branch, so it enqueues no task.

A member mention therefore does NOT make a person "run", and this skill does NOT claim it delivers a notification through the Go comment handler — there is no such code path in that handler (see the source map). What is verified is the contract above: only agent and squad mentions enqueue work.

Preview and per-comment suppression

Newer clients can call POST /api/issues/{id}/comments/trigger-preview before creating or editing a comment. The preview endpoint uses the same computeCommentAgentTriggers function as create and edit re-triggering, so the displayed agent chips come from backend rules, not from a client-side reimplementation.

When previewing an edit, clients may send editing_comment_id. The server validates that the comment belongs to the same workspace and issue, derives or checks the edit's parent comment context, and excludes only pending tasks whose trigger_comment_id is that same comment. Pending tasks from any other comment on the issue still dedupe the preview.

When creating or editing a comment, clients may send an optional suppress_agent_ids array. The server still computes the full trigger set first, then removes those agent IDs as a post-filter. A missing or empty field preserves the old behavior. A valid UUID that is not in the computed trigger set is a no-op; a malformed UUID is rejected at the request boundary.

@all is the broadcast type

@all uses the literal all, never a UUID:

[@all](mention://all/all)

It addresses everyone on the issue. It does NOT make any specific agent run. And it is special at trigger time: in commentMentionsOthersButNotAssignee (server/internal/handler/comment.go), a comment that carries an @all mention is treated as a broadcast that SUPPRESSES the issue assignee's automatic on-comment trigger. Use @all to announce, not to request work from the assignee.

What does NOT happen (so the result doesn't surprise you)

These are all silent no-ops — no error, no run:

• A name where a UUID belongs. mention://member/Alice is dead. The id group accepts only hex+dashes or all; the non-hex letters in a typical name make the whole pattern fail to match, so the parser returns nothing.
• A hex-ish but wrong UUID. A well-formed-looking UUID that no entity owns DOES parse, then no-ops at lookup: the workspace-scoped query finds no agent and the loop continues. Same agent-visible result (nothing fires), but the mechanism is the lookup miss, not a parse failure.
• An already-pending task. Even a correct @agent/@squad is skipped when the target already has a pending task on this issue (HasPendingTaskForIssueAndAgent → continue). Edit preview is the only exception: editing_comment_id ignores pending tasks from the same comment being edited, because save cancels those old tasks before it re-computes triggers. It is still comment-scoped, not an agent-wide bypass.
• An archived agent, or a squad whose leader is archived: skipped (RuntimeID invalid or ArchivedAt set).
• A private agent you cannot access: skipped — the mention path gates on canAccessPrivateAgent directly for both @agent and @squad (the canEnqueueSquadLeader wrapper is the assignment/child-done path, not this one).

Incorrect → Correct

Incorrect: @alice please review → plain text, no link, parses to nothing, nobody is reached.

Incorrect: [@Alice](mention://member/Alice) please review → "Alice" is not a UUID; the id group rejects the non-hex letters, the pattern does not match, the link is silently dead.

Correct:

1. multica workspace member list --output json → Alice's user_id = 7f3a…
2. [@Alice](mention://member/7f3a…) please review → a real user_id parses; the link renders and resolves to Alice.

@all broadcast: [@all](mention://all/all) heads up — addresses everyone, runs no specific agent, and suppresses the assignee auto-trigger.

These exact shapes are pinned by a Go behavior test (TestMentioningSkillTeachesTheParserContract) that feeds them through util.ParseMentions: the name form parses to nothing, the real-UUID form parses, @all parses to {all, all}, and a wrong type with a real UUID still parses (which is why the type must match the id source).

References

references/mentioning-source-map.md — file:line evidence for the regex, the enqueue branches, the @all suppression, and the CLI id-source mapping, plus the explicit note that no member-notification delivery path exists in the Go comment handler.