board
The layer around the official Multica CLI skill — where the binary hides in a desktop-app install, how to reach it from a bridged Cowork/claude.ai session, the shell and JSON shapes that bite, the pla
SKILL.mdplugins/multica-ops/skills/board/SKILL.md
GitHubMultica: the parts around the command reference
0. The command reference is not this skill
Multica publishes the canonical CLI skill at
multica-ai/multica-cli. It is well maintained —
a linter runs its documented commands against the real binary daily, on both the minimum and
latest CLI — and it is the authority on the command surface:
/plugin marketplace add multica-ai/multica-cli
/plugin install multica-cli@multica-cli
Go there for: issue search semantics, the comment read modes (--roots-only --summary,
--thread --tail, --recent capping threads not comments, --compact, --full), the
working-directory restriction on --content-file / --description-file / --attachment, when
--parent is mandatory, the mention:// side effects, metadata versus custom properties,
subscribers, run inspection and cancellation, sub-issue stages, and PR linking.
Do not restate any of that here. Two skills that describe the same commands will disagree eventually, and the session obeys whichever it read first. This skill covers what that reference does not, and the moment it starts to overlap, the overlap is the bug.
If the reference is not installed, say so before operating a board — the safe defaults for mentions, status side effects and comment writes live there.
1. Finding the binary in a desktop-app install
The reference assumes multica is on PATH (a package-manager install). With the desktop app
it is not, and command -v multica returning nothing is expected — the reference's very first
step, multica version, fails there.
M="${MULTICA_BIN:-/Applications/Multica.app/Contents/Resources/app.asar.unpacked/resources/bin/multica}"
"$M" --version
ls ~/.multica/profiles # the profile names on this machine
P="${MULTICA_PROFILE:-<one of those>}"
"$M" --profile "$P" workspace list --output json # -> [{id, name, slug}, …]
Record the version next to any claim you make about the surface. The CLI ships changes almost
daily; the output shapes in §4 were first measured on v0.4.42, and everything added since —
the control-character note, the parent_issue_id note, the reply-routing rule in §5 — on
v0.4.44, between 19 and 20/09/2026.
2. Two routes, and only one is direct
Claude Code on the machine with the desktop app — run the CLI in the shell. Done.
A Cowork or claude.ai session bridged to that machine — the session's own shell runs in a
separate sandbox with only the connected folders mounted. It cannot see /Applications, so it
cannot reach the CLI. The route that works is the bridge's shell on the user's machine (on
macOS, an AppleScript do shell script "…"), and three things bite there:
- Nested quoting breaks easily — avoid
python3 -cwith inner quotes. Write output to a file inside a connected folder and read it from the sandbox. - That shell reports any non-zero exit as a tool error, even a
whichthat finds nothing. End with; echo done, or|| true, when the exit code does not matter. - The sandbox usually cannot delete files in connected folders. Clean up from the same bridge shell that created them.
With the desktop app closed, neither route exists. Say so and move on.
3. Shell gotchas that have produced real defects
Mostly zsh, the macOS default:
- A variable holding several flags becomes one argument.
"$M" $flags --helpfails. Wrap it:mt(){ "$M" --profile "$P" --workspace-id "$WS" "$@"; }— or drive the CLI from Python'ssubprocess. for x in $VARiterates once. Use${=VAR}or a real array. This has silently produced batches of issues carrying an invalid--workspace a b.- zsh arrays are 1-indexed:
${A[0]}is empty, which is how an issue gets created with a blank field. pipestatusis lowercase, andEXIT=$?after a pipeline measures the last command:bash script | tailgives youtail's exit code. This is not theoretical: on 20/09/2026 an&&chain continued past a gate harness that had just printed 4 FAIL, because the exit read wastail's. Capture first, then test —OUT="$(cmd 2>&1)"; RC=$?before any filter — orset -o pipefail. Reading a gate's verdict out of a pipeline is how a session tells the board something passed when it did not.- Expand a variable with braces when anything follows it.
git show $TB:pathappends the path to the variable name, so zsh looks up$TB:path— measured on 20/09/2026, it produced the nonexistent reftech-676-2-17-1k-changelog-local.shand a confusing "not found". Writegit show "${TB}:path". trwith sets of different lengths does not error — it pads.tr 'A-Z-' 'a-z'has 27 source characters and 26 destination ones, so the extra one (-) maps to the last destination character:LAS-114becomeslasz114. On 20/09/2026 this silently pointed 17 evidence commands at filenames that did not exist and produced 17 false FAIL, one step before they would have been written to seven issues. Keep the sets the same length, or delete in a pass of its own (tr -d '-'). The general shape — a shell builtin that mangles instead of failing — is the argument for §8's rule that a board write never shares a chain with a step that can fail.- An unquoted heredoc executes backticks, and prose about the shell is full of them. Writing
a board comment with
<<EOF— unquoted, because you need to interpolate a SHA — makes every`command`in the body a command substitution. On 20/09/2026 a comment whose text mentioned`git ls-files`as the name of a tool shipped with 440 lines of repository listing spliced into it, and the two sibling comments in the same batch were clean only because they happened to name no commands. Use<<'EOF'and substitute the variable parts afterwards, or build the file in Python. The rule generalises: the moment a body talks about shell, the heredoc must be quoted. - Agent shells often abort on the first non-zero exit. Guard commands whose non-zero exit is a
normal outcome — a drift check that exits 1 on "differs" — with
|| trueorset +e. - BSD grep has no
\s(use[[:space:]]), and--include=*.mdneeds quoting in zsh.
4. Output shapes and cost flags the reference does not state
Measured on v0.4.42, against reference v1.1.0:
--limitcaps at 100 (default 50); above it the CLI refuses and tells you to page. Paging is subtle: advance--offsetby the number of issues in the response you just got, usinghas_morefrom the JSON — not by your requested page size.issue list --fields id,title,status,…trims the returned object client-side, explicitly to cut agent context cost. It is the cheapest flag on the whole board surface and it is absent from the reference.issue children --output jsonreturns{stages, total, unstaged}, not an array. Iterate.stages[]and check(.unstaged|length) == 0; a bare.[]walks three heterogeneous values without erroring.issue comment listreturns a bare list, not{comments: […]}.- Any string field a person typed can carry raw control characters — a comment body, an
issue description, an agent's instructions — and a strict JSON parser fails on the first
one. It is intermittent, which is worse than constant: measured on v0.4.44, five outputs
(
issue get,issue list,issue comment list,agent get,project get) parsed strictly, and the sessions of 18–19/09/2026 hit bodies that did not. Parse leniently by default, because it costs nothing on clean output and a strict parser dying on the one body that carries a control character, in the middle of a batch, is what breaks a chain:json.loads(raw, strict=False)in Python, or strip[\x00-\x08\x0b\x0c\x0e-\x1f]before a strict parser or beforejq. autopilot getwraps its payload in{"autopilot": {…}}; the othergetcommands do not.--summarytruncates the body to roughly 200 characters, silently. It is a display affordance onissue comment list, and--output jsondoes not turn it off: the JSON carries the shortened string with a trailing…. Measured on 20/09/2026 — the same comment reads 201 characters with--summaryand 2431 without. Harmless while you are scanning threads, which is what the flag is for; wrong the moment you use that read to verify what you wrote. A session that posts a long comment and then measures it with--summaryconcludes it was truncated on the way out, and "fixes" a comment that was already complete. Verify writes with a read that has no--summary.issue comment list --threadprints a cursor line before the JSON.Next reply cursor: --before … --before-id …lands on stdout ahead of the array, so a strict parser dies on character 1 and the error looks like malformed JSON rather than a prefix. Strip to the first[(sed -n '/^\[/,$p') before parsing.- An issue's parent is
parent_issue_id, notparent_id.parent_idis a real field — on a comment, where it marks the thread — so a parser that reaches for it on an issue getsNoneinstead of an error, and the session concludes the issue is top-level. Measured on 20/09/2026 against LAS-69, which reads as parentless throughparent_idand is in fact stage 3 under LAS-40. When a field comes back empty and the answer matters, print the object's keys before believing the absence. status_categorycollapses custom review statuses together; only.statusseparates them, andstatus_namecomes back empty for custom statuses insidechildren.trigger_comment_idexists only on runs ofkind: comment. Adirectrun carriesattribution: issue_assignmentwithsource: direct_human; one started by an agent on a human's behalf carriessource: delegationwith the humaninitiatorpreserved.issue timelineanswers "when did this reach review" and "how long has it sat here" — the reference does not mention it, and its own linter flags that.--content-stdin/--description-stdin/--context-stdinexist and the CLI's own help recommends them for multi-line bodies. The reference prescribes files only, which is the portable choice (stdin mangles non-ASCII on Windows) — on macOS, stdin sidesteps the working-directory restriction and leaves no file to clean up.
5. What wakes an agent when you comment
The reference covers the mention:// links. It does not cover the implicit routing, and
that is what costs money by accident: a plain comment carrying no mention at all can start a
run. These rules come from Multica's own product documentation and the server's comment-routing
code, not from inference.
- A comment whose first whitespace-delimited token is
/note(case-insensitive) triggers nothing at all — mentions inside it included, because the check runs before mentions are parsed. It posts as an ordinary comment and the token stays in the body. This is the one-command way to write on an issue without waking anyone. @allnotifies every member and switches off the assignee fallback for that comment. It does not reach agents: agents have no inbox.- With neither of those, routing follows the discussion: a reply to an agent's comment goes to that agent; a reply inside a discussion an agent already joined stays with that agent; a top-level comment matching neither goes to the issue's agent assignee (the leader, when the assignee is a squad). A plain reply to a member's comment does not fall back to the assignee. Any explicit mention — including of a member — cancels the fallback.
- "A reply to a member's comment is safe" holds only when the root carries no agent mention.
A thread inherits its root: reply inside a discussion whose root text mentions an agent, and
that agent is enqueued — even when both the root and your reply were written by a member, and
even when your reply mentions nobody. Measured on 19/09/2026 (CLI v0.4.44): five replies by the
same human to their own comments, under roots that named the Adversarial Reviewer, started five
extra Reviewer runs and duplicated a whole review round. Before replying in a thread, read the
root. To amend or complete a review request already posted, start the comment with
/note; if it genuinely needs to wake someone, post a fresh top-level request with the right head and cancel the wrong run withissue cancel-task <run-id>first. Either way, confirm withissue runsafterwards — the queue, not your intent, is the record. - The assignee fallback fires in any status, closed issues included. Comments are conversational and follow-up questions on finished work are expected behaviour. A terminal status is not a safe place to write.
- A run is not idle just because its status is not
queued,runningorpending.waiting_local_directoryis a live state: the run holds a place in the queue waiting for the target repository's local checkout, and several runs against the same repository serialise behind it. Measured on 20/09/2026, asking three reviews on one repository at once: one ran and two sat inwaiting_local_directoryuntil it finished. A liveness check written as an allow-list of busy states reports them as idle — and "no run is alive" is exactly the precondition for merging. Decide liveness by a deny-list of terminal states (completed,failed,cancelled, …) and treat anything unrecognised as alive: an unknown status is far more likely to be a new busy state than a new finished one. - It is skipped when the assignee has no runtime, is archived, you cannot invoke it, or it already holds a pending run on that issue — consecutive comments coalesce into the waiting run rather than starting a second one.
issue comment addhas no--no-start. That flag exists onissue status,issue assignandissue update, and nowhere else. Anything claiming otherwise — including a confident answer from a search engine — is wrong;--helpsettles it in one second.
So the recipe for commenting on an agent-assigned issue without starting a run is a /note
prefix, not an unassign-comment-reassign dance. The dance works, but it mutates ownership for
the duration and is not needed.
6. Platform limits worth knowing before you promise something
- Workspace isolation is real. An agent running in one workspace cannot read another; only a human profile's CLI sees more than one. Cross-workspace search, dependencies and any portfolio view exist only through that CLI. When writing anything that governs agents, ask whether it assumes an agent can see a neighbouring workspace — if it does, that is a defect.
- Agents cannot produce artifacts. In an agent task the artifact tool is disabled and the
refusal is explicit:
Artifact is disabled for this session, in subagents as well as here. Delegating to a subagent does not work around it. Attach a file to a comment instead. - There is no MCP surface on the CLI — but
agent updatetakes--mcp-config,--mcp-config-stdinand--mcp-config-file, so agents consume MCP servers. The useful question is which servers your agents should have, not how to wrap the CLI in one. Pass that config by stdin or file: on the command line it lands in shell history andps. agent create --descriptioncaps at 255 characters, and--instructionstakes a string, not a path.- Scheduled autopilots take a full cron expression and an IANA timezone
(
autopilot trigger-add --kind schedule --cron … --timezone …), andautopilot createtakes--subscriber.trigger-add --helpdocuments the--timezonedefault as UTC (v0.6.1, 03/10/2026), so a cron written as the hour a person reads it lands hours off unless you pass the zone that person lives by:--cron '0 9 * * 1' --timezone America/Sao_Paulofor 09:00 on Mondays in Brasília. Sub-hourly expressions are writable; whether the server honours a given granularity is a test, not a promise.
7. When a repository governs the board
A team running Multica seriously keeps its agent instructions, workspace skills, workspace
context and project descriptions versioned in a repository and pushes them to the server
through the CLI. If MULTICA_PLAYBOOK is set, or the working tree looks like such a repo, that
repository outranks this skill and the reference on everything it declares.
Read before acting, in this order: the repo's agent-context file (CLAUDE.md / AGENTS.md)
for the rules that bind you; the root README for what each directory is and which of them
deploy; the per-workspace manifest for ids; and the scripts directory for the drift check and
the deploy tool.
The constraints such a repo almost always encodes — assume them until its own text says otherwise:
- Editing is not deploying. A file in that repo is operational text; the live system
changes only when
agent update,skill update,workspace update,project updateorautopilot updateruns. A commit changes nothing on the server. Saying "the agent now does X" because the file says X, with no deployment, is a false statement about the system. - Deployment is a human act. Never run those five commands on your own. Propose the diff, name the file, and stop. If the repo ships a deploy script, its dry-run is yours to use and its apply mode is not.
- Ids come from the manifest, never from memory or from a listing you skimmed. The
manifest is generated from the server and diffable; that is the point of it. Read it by
the key it actually uses: agents and skills are keyed by
name:, projects and autopilots bytitle:— agrep 'name: <project>'finds nothing and says so, which is the good case; the bad case is reaching for a listing instead, or for memory. - Measure drift before you claim state. If the repo ships a drift check, run it and read its exit code as state, not as failure — "differs" is the normal condition before a deployment.
- A committed-but-undeployed change is tracked work, not a paragraph. Register it wherever that repo says pending work lives — a board item, not a heading in a versioned file, which is how status silently goes stale.
- Text that governs other agents is not yours to change unilaterally. Behavioural rules, status contracts, backlog policy and review thresholds are decisions of whoever owns the system. Propose in diff; a taken decision gets recorded where that repo records decisions.
- No credentials in any of that text. Instructions are stored server-side and passed through process arguments.
- Shared text must not hardcode one workspace's ids. A registry id from workspace A deployed into workspace B points at nothing, and the failure is silent. Render it from the manifest, or write the sentence without the id.
Before writing anything into such a repo, ask yourself the two questions it exists to enforce: does this change behaviour on the server (then it needs a deployment, tracked), and does it assume an agent can see a workspace it cannot?
8. Conduct on the board
The reference covers the mechanics of side effects. These are the habits around them:
- Scoping is a human gate. Promoting an item out of the unscoped column is where a person's decision is cheap and changes the outcome; leave it to them, and do not comment on an unscoped item — that comment is written to nobody.
- Acts performed with a human's profile are indistinguishable from that human in
issue timeline. When a session acts, leave a dated note saying so, with the hour in the zone that person reads, the zone written out, and UTC beside it so the note can be matched against the API's stamps, which come in UTC:18:41 BRT (21:41Z), not18:41and not21:41Zalone. When the UTC falls on another calendar day than the local hour, it carries its date, so the note is not matched against the wrong day:22:59 BRT (04/10 01:59Z). The date is day/month, as a Brazilian reader writes it; a reader used to month/day (the US) would take04/10for 10 April. An hour with no zone cannot be placed against those stamps. - Never create a registry object — agent, skill, project, autopilot — casually. It will appear in no manifest and no drift check will see it.
- A write to the board never shares a command chain with a step that can fail. Verify
first — the id resolves, the file exists, the status is what you expect — and then write,
as a command of its own.
|| trueon a probe is fine;|| trueon the write, or a write that runs because the probe before it "succeeded" with garbage, is how a note lands on the wrong issue. In zsh,set -edoes not cover a command substitution nor a Python heredoc: guard those with an explicit|| exit 1. - Before merging a PR that a human session conducted, read
issue runs <ID>andissue timeline <ID>on the issue it closes. An agent run may be alive on the same PR — a review round nobody asked for, a conductor about to merge — and two conductors on one PR is how a merge lands under the human's login with no record of who decided it. On 18/09/2026 a human session merged a PR while the conductor agent was still running review rounds on it. The stage barrier woke the conductor 2 s after the merge — by the platform's own mention in asystemcomment, not by anyone's verdict; the review verdict landed 52 s after the merge and woke it again; it opened two follow-up issues at 150 s and 158 s, from a verdict that was no longer its to act on (measured at the source on 19/09/2026: the PR'smergedAt,issue comment liston the two issues involved, the issues'created_at). /notewrites without waking anyone, and that is all it does: it addresses nothing to anyone. A pending item, a follow-up or a correction that lives only in a/noteis written to nobody — the same failure as a comment on an unscoped item, from the other side. Anything that must be done goes where it will be found: a checkbox with averify:in the issue description, or an issue of its own.- A description write replaces the whole field, and nothing merges it.
issue update --description-*writes the entire description; the CLI has no compare-and-set (no--if-revisionas of v0.5.3 —revisioncomes back on read and cannot be passed on write). Two writers that read, edit and write back erase each other in silence, with no conflict and an ordinaryactivityevent in thetimeline. Measured on 21/09/2026 on LAS-69: a session marked ten DoD boxes at 16:39:04Z and another added twoverify:criteria at 17:04:45Z, with two more description writes in between; nothing was lost only because of the order. The cost grows with the rule above — the more pending work lives as checkboxes in descriptions, the more a lost write costs. Three habits close most of the window: read immediately before writing (never write back a read from earlier in the turn); change only your substring — exact replacement asserted to occur once, or an append — instead of re-emitting an edited copy; and check the window after writing, which takes one check for each half of it. A write landing after yours shows in the content: re-read and compare with what you wrote — content, notupdated_at, ignoring trailing whitespace (on 21/09/2026 a trailing newline fromprint()was enough for a false alarm on the first write, which is how a check gets abandoned). A write landing before yours was erased by yours, so the re-read shows your text and only thetimelineshows it: count thedescription_updatedevents before reading the description (N) and again after writing (M); exactly one new event, and that one with your own id as itsactor_id, means yours alone. Your id is your profile's (user profile get), except inside an agent task: there the write carries the agent's id,MULTICA_AGENT_ID, whileuser profile getreturns the member who owns the token (v0.5.3, 24/09/2026: task events on LAS-140 and LAS-141; the CLI sends the variable asX-Agent-Id). Wait for that one: an event by someone else showing first is not it. A writer with your id does look like you — another session on the same profile, the person it belongs to editing in the app (see above; not measured: which id an app edit carries), another run of the same agent — and while yours is late it passes for yours. The order is the point — a write landing between a read and a later count entersNwhile the text in hand is already stale. Measured on 24/09/2026 (v0.5.2, on a throwaway issue): every description write logged adescription_updated, even one identical to the stored text, so a write that changes nothing must not be sent at all. Two shortcuts fail.revisionalso moves on a comment, a reply, a title or status change and on writes thetimelinedoes not show (47 of 100lassissues had more revisions than visible events on 24/09/2026), so a jump is not proof of a description write. And--sincedrops the whole second it is given (v0.5.3, 24/09/2026, LAS-147: the event at 2026-09-21T20:07:03Z is missing from--since 2026-09-21T20:07:03Zand present from--since 2026-09-21T20:07:02Z), while an issue'supdated_atis, as a rule, the second of its last event (96 of 100lassissues on 24/09/2026) — so--since <updated_at>is blind to the very write that matters; to search by hand, start one second earlier. An erased write has nothing to be restored from: the event keeps no text (detailsis empty) and the CLI has no history command. Do not write over it again; its author — the event'sactor_typeandactor_id— re-applies it, and to an agent that request is a mention, which starts a run (§5). When thatactor_idis your own id, the event does not say which of those writers made it: ask whoever runs them, which thetimelinecannot answer.scripts/patch-description.pyin this skill does all of it: it exits 1 without writing when a substring does not occur exactly once, an insertion (a replacement whose new text contains the old) or the append is already there, or the edits change nothing — so a re-run after an exit 3 writes nothing if an edit survived; 2 on--editsthat are not pairs of two strings, or an empty append; and 3 when the re-read differs, there is not exactly one new event, or none by your id, printing the read'supdated_at,revisionbefore and after, each new event with its author (yours marked), and the command that lists them.