Multica: 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 -c with 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
which that 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 --help fails. Wrap
it: mt(){ "$M" --profile "$P" --workspace-id "$WS" "$@"; } — or drive the CLI from Python's
subprocess.
for x in $VAR iterates 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.
pipestatus is lowercase, and EXIT=$? after a pipeline measures the last command:
bash script | tail gives you tail'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
was tail's. Capture first, then test — OUT="$(cmd 2>&1)"; RC=$? before any filter — or
set -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:path appends the
path to the variable name, so zsh looks up $TB:path — measured on 20/09/2026, it produced
the nonexistent ref tech-676-2-17-1k-changelog-local.sh and a confusing "not found".
Write git show "${TB}:path".
tr with 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-114 becomes lasz114. 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
|| true or set +e.
- BSD grep has no
\s (use [[:space:]]), and --include=*.md needs quoting in zsh.
4. Output shapes and cost flags the reference does not state
Measured on v0.4.42, against reference v1.1.0:
--limit caps at 100 (default 50); above it the CLI refuses and tells you to page.
Paging is subtle: advance --offset by the number of issues in the response you just got,
using has_more from 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 json returns {stages, total, unstaged}, not an array. Iterate
.stages[] and check (.unstaged|length) == 0; a bare .[] walks three heterogeneous
values without erroring.
issue comment list returns 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 before jq.
autopilot get wraps its payload in {"autopilot": {…}}; the other get commands do not.
--summary truncates the body to roughly 200 characters, silently. It is a display
affordance on issue comment list, and --output json does 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 --summary and 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 --summary concludes 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 --thread prints 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, not parent_id. parent_id is a real field — on a
comment, where it marks the thread — so a parser that reaches for it on an issue gets None
instead of an error, and the session concludes the issue is top-level. Measured on 20/09/2026
against LAS-69, which reads as parentless through parent_id and 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_category collapses custom review statuses together; only .status separates them,
and status_name comes back empty for custom statuses inside children.
trigger_comment_id exists only on runs of kind: comment. A direct run carries
attribution: issue_assignment with source: direct_human; one started by an agent on a
human's behalf carries source: delegation with the human initiator preserved.
issue timeline answers "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-stdin exist 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.
@all notifies 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 with issue cancel-task <run-id> first. Either way, confirm with
issue runs afterwards — 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, running or pending.
waiting_local_directory is 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 in waiting_local_directory until 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 add has no --no-start. That flag exists on issue status, issue assign
and issue update, and nowhere else. Anything claiming otherwise — including a confident
answer from a search engine — is wrong; --help settles 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 update takes --mcp-config,
--mcp-config-stdin and --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 and ps.
agent create --description caps at 255 characters, and --instructions takes a string, not
a path.
- Scheduled autopilots take a full cron expression and an IANA timezone
(
autopilot trigger-add --kind schedule --cron … --timezone …), and autopilot create takes
--subscriber. trigger-add --help documents the --timezone default 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_Paulo for 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 update or
autopilot update runs. 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
by title: — a grep '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), not 18:41 and not 21:41Z alone.
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 take
04/10 for 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.
|| true on a probe is fine; || true on 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 -e does 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> and
issue 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 a system comment, 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's mergedAt, issue comment list on the
two issues involved, the issues' created_at).
/note writes 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 /note is
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 a verify:
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-revision as of v0.5.3 — revision comes 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 ordinary activity event in the timeline. Measured on 21/09/2026 on LAS-69: a session
marked ten DoD boxes at 16:39:04Z and another added two verify: 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, not updated_at, ignoring trailing whitespace (on 21/09/2026 a
trailing newline from print() 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 the timeline shows it: count the description_updated events
before reading the description (N) and again after writing (M); exactly one new event,
and that one with your own id as its actor_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, while user profile get returns 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 as X-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 enters N while the text in hand is already stale. Measured
on 24/09/2026 (v0.5.2, on a throwaway issue): every description write logged a
description_updated, even one identical to the stored text, so a write that changes nothing
must not be sent at all. Two shortcuts
fail. revision also moves on a comment, a reply, a title or status change and on writes the
timeline does not show (47 of 100 lass issues had more revisions than visible events on
24/09/2026), so a jump is not proof of a description write. And --since drops 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:03Z and present from --since 2026-09-21T20:07:02Z), while an
issue's updated_at is, as a rule, the second of
its last event (96 of 100 lass issues 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 (details is empty) and the CLI has no
history command. Do not write over it again; its author — the event's actor_type and
actor_id — re-applies it, and to an agent that request is a mention, which starts a run
(§5). When that actor_id is your own id, the event does not say which of those writers made
it: ask whoever runs them, which the timeline cannot answer. scripts/patch-description.py
in 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 --edits that 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's updated_at, revision before and after, each new event with its author (yours
marked), and the command that lists them.
1---2name: board3description: 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 platform limits, and how to work a board that is governed by a repository which versions its Multica configuration. Use alongside the official `multica-cli` skill whenever a task touches a Multica board.4metadata:5 source: https://skillmd.com/skills/fernando-bertholdo/board6---78# Multica: the parts around the command reference910## 0. The command reference is not this skill1112Multica publishes the canonical CLI skill at13[`multica-ai/multica-cli`](https://github.com/multica-ai/multica-cli). It is well maintained —14a linter runs its documented commands against the real binary daily, on both the minimum and15latest CLI — and it is the authority on the command surface:1617```text18/plugin marketplace add multica-ai/multica-cli19/plugin install multica-cli@multica-cli20```2122Go there for: `issue search` semantics, the comment read modes (`--roots-only --summary`,23`--thread --tail`, `--recent` capping *threads* not comments, `--compact`, `--full`), the24working-directory restriction on `--content-file` / `--description-file` / `--attachment`, when25`--parent` is mandatory, the `mention://` side effects, metadata versus custom properties,26subscribers, run inspection and cancellation, sub-issue stages, and PR linking.2728**Do not restate any of that here.** Two skills that describe the same commands will disagree29eventually, and the session obeys whichever it read first. This skill covers what that30reference does not, and the moment it starts to overlap, the overlap is the bug.3132If the reference is not installed, say so before operating a board — the safe defaults for33mentions, status side effects and comment writes live there.3435## 1. Finding the binary in a desktop-app install3637The reference assumes `multica` is on `PATH` (a package-manager install). With the desktop app38it is not, and `command -v multica` returning nothing is expected — the reference's very first39step, `multica version`, fails there.4041```bash42M="${MULTICA_BIN:-/Applications/Multica.app/Contents/Resources/app.asar.unpacked/resources/bin/multica}"43"$M" --version44ls ~/.multica/profiles # the profile names on this machine45P="${MULTICA_PROFILE:-<one of those>}"46"$M" --profile "$P" workspace list --output json # -> [{id, name, slug}, …]47```4849Record the version next to any claim you make about the surface. The CLI ships changes almost50daily; the output shapes in §4 were first measured on **v0.4.42**, and everything added since —51the control-character note, the `parent_issue_id` note, the reply-routing rule in §5 — on52**v0.4.44**, between 19 and 20/09/2026.5354## 2. Two routes, and only one is direct5556**Claude Code on the machine with the desktop app** — run the CLI in the shell. Done.5758**A Cowork or claude.ai session bridged to that machine** — the session's own shell runs in a59separate sandbox with only the connected folders mounted. It cannot see `/Applications`, so it60cannot reach the CLI. The route that works is the bridge's shell on the user's machine (on61macOS, an AppleScript `do shell script "…"`), and three things bite there:6263- Nested quoting breaks easily — avoid `python3 -c` with inner quotes. Write output to a file64 inside a connected folder and read it from the sandbox.65- That shell reports any non-zero exit as a tool error, even a `which` that finds nothing. End66 with `; echo done`, or `|| true`, when the exit code does not matter.67- The sandbox usually cannot delete files in connected folders. Clean up from the same bridge68 shell that created them.6970With the desktop app closed, neither route exists. Say so and move on.7172## 3. Shell gotchas that have produced real defects7374Mostly zsh, the macOS default:7576- **A variable holding several flags becomes one argument.** `"$M" $flags --help` fails. Wrap77 it: `mt(){ "$M" --profile "$P" --workspace-id "$WS" "$@"; }` — or drive the CLI from Python's78 `subprocess`.79- `for x in $VAR` iterates **once**. Use `${=VAR}` or a real array. This has silently produced80 batches of issues carrying an invalid `--workspace a b`.81- zsh arrays are **1-indexed**: `${A[0]}` is empty, which is how an issue gets created with a82 blank field.83- `pipestatus` is lowercase, and `EXIT=$?` after a pipeline measures the *last* command:84 `bash script | tail` gives you `tail`'s exit code. This is not theoretical: on 20/09/2026 an85 `&&` chain continued past a gate harness that had just printed 4 FAIL, because the exit read86 was `tail`'s. Capture first, then test — `OUT="$(cmd 2>&1)"; RC=$?` before any filter — or87 `set -o pipefail`. Reading a gate's verdict out of a pipeline is how a session tells the board88 something passed when it did not.89- **Expand a variable with braces when anything follows it.** `git show $TB:path` appends the90 path to the *variable name*, so zsh looks up `$TB:path` — measured on 20/09/2026, it produced91 the nonexistent ref `tech-676-2-17-1k-changelog-local.sh` and a confusing "not found".92 Write `git show "${TB}:path"`.93- **`tr` with sets of different lengths does not error — it pads.** `tr 'A-Z-' 'a-z'` has 2794 source characters and 26 destination ones, so the extra one (`-`) maps to the last destination95 character: `LAS-114` becomes `lasz114`. On 20/09/2026 this silently pointed 17 evidence96 commands at filenames that did not exist and produced **17 false FAIL**, one step before they97 would have been written to seven issues. Keep the sets the same length, or delete in a pass of98 its own (`tr -d '-'`). The general shape — a shell builtin that mangles instead of failing —99 is the argument for §8's rule that a board write never shares a chain with a step that can100 fail.101- **An unquoted heredoc executes backticks, and prose about the shell is full of them.** Writing102 a board comment with `<<EOF` — unquoted, because you need to interpolate a SHA — makes every103 `` `command` `` in the body a command substitution. On 20/09/2026 a comment whose text104 *mentioned* `` `git ls-files` `` as the name of a tool shipped with **440 lines of repository105 listing** spliced into it, and the two sibling comments in the same batch were clean only106 because they happened to name no commands. Use `<<'EOF'` and substitute the variable parts107 afterwards, or build the file in Python. The rule generalises: the moment a body talks *about*108 shell, the heredoc must be quoted.109- Agent shells often abort on the first non-zero exit. Guard commands whose non-zero exit is a110 normal outcome — a drift check that exits 1 on "differs" — with `|| true` or `set +e`.111- BSD grep has no `\s` (use `[[:space:]]`), and `--include=*.md` needs quoting in zsh.112113## 4. Output shapes and cost flags the reference does not state114115Measured on v0.4.42, against reference v1.1.0:116117- `--limit` caps at **100** (default 50); above it the CLI refuses and tells you to page.118 Paging is subtle: advance `--offset` by the **number of issues in the response you just got**,119 using `has_more` from the JSON — not by your requested page size.120- `issue list --fields id,title,status,…` trims the returned object client-side, explicitly to121 cut agent context cost. It is the cheapest flag on the whole board surface and it is absent122 from the reference.123- `issue children --output json` returns `{stages, total, unstaged}`, not an array. Iterate124 `.stages[]` and check `(.unstaged|length) == 0`; a bare `.[]` walks three heterogeneous125 values without erroring.126- `issue comment list` returns a bare list, not `{comments: […]}`.127- **Any string field a person typed can carry raw control characters** — a comment body, an128 issue description, an agent's instructions — and a strict JSON parser fails on the first129 one. It is intermittent, which is worse than constant: measured on v0.4.44, five outputs130 (`issue get`, `issue list`, `issue comment list`, `agent get`, `project get`) parsed131 strictly, and the sessions of 18–19/09/2026 hit bodies that did not. Parse leniently by132 default, because it costs nothing on clean output and a strict parser dying on the one133 body that carries a control character, in the middle of a batch, is what breaks a chain:134 `json.loads(raw, strict=False)` in Python, or strip `[\x00-\x08\x0b\x0c\x0e-\x1f]`135 before a strict parser or before `jq`.136- `autopilot get` wraps its payload in `{"autopilot": {…}}`; the other `get` commands do not.137- **`--summary` truncates the body to roughly 200 characters, silently.** It is a display138 affordance on `issue comment list`, and `--output json` does not turn it off: the JSON carries139 the shortened string with a trailing `…`. Measured on 20/09/2026 — the same comment reads 201140 characters with `--summary` and 2431 without. Harmless while you are scanning threads, which141 is what the flag is for; wrong the moment you use that read to **verify what you wrote**. A142 session that posts a long comment and then measures it with `--summary` concludes it was143 truncated on the way out, and "fixes" a comment that was already complete. Verify writes with144 a read that has no `--summary`.145- **`issue comment list --thread` prints a cursor line before the JSON.** `Next reply cursor:146 --before … --before-id …` lands on stdout ahead of the array, so a strict parser dies on147 character 1 and the error looks like malformed JSON rather than a prefix. Strip to the first148 `[` (`sed -n '/^\[/,$p'`) before parsing.149- **An issue's parent is `parent_issue_id`, not `parent_id`.** `parent_id` is a real field — on a150 *comment*, where it marks the thread — so a parser that reaches for it on an issue gets `None`151 instead of an error, and the session concludes the issue is top-level. Measured on 20/09/2026152 against LAS-69, which reads as parentless through `parent_id` and is in fact stage 3 under153 LAS-40. When a field comes back empty and the answer matters, print the object's keys before154 believing the absence.155- `status_category` collapses custom review statuses together; only `.status` separates them,156 and `status_name` comes back empty for custom statuses inside `children`.157- `trigger_comment_id` exists only on runs of `kind: comment`. A `direct` run carries158 `attribution: issue_assignment` with `source: direct_human`; one started by an agent on a159 human's behalf carries `source: delegation` with the human `initiator` preserved.160- `issue timeline` answers "when did this reach review" and "how long has it sat here" — the161 reference does not mention it, and its own linter flags that.162- `--content-stdin` / `--description-stdin` / `--context-stdin` exist and the CLI's own help163 recommends them for multi-line bodies. The reference prescribes files only, which is the164 portable choice (stdin mangles non-ASCII on Windows) — on macOS, stdin sidesteps the165 working-directory restriction and leaves no file to clean up.166167## 5. What wakes an agent when you comment168169The reference covers the `mention://` links. It does not cover the **implicit** routing, and170that is what costs money by accident: a plain comment carrying no mention at all can start a171run. These rules come from Multica's own product documentation and the server's comment-routing172code, not from inference.173174- A comment whose **first whitespace-delimited token is `/note`** (case-insensitive) triggers175 nothing at all — mentions inside it included, because the check runs before mentions are176 parsed. It posts as an ordinary comment and the token stays in the body. This is the177 one-command way to write on an issue without waking anyone.178- `@all` notifies every member and switches off the assignee fallback for that comment. It does179 not reach agents: agents have no inbox.180- With neither of those, routing follows the discussion: a reply to an agent's comment goes to181 that agent; a reply inside a discussion an agent already joined stays with that agent; a182 **top-level** comment matching neither goes to the issue's **agent assignee** (the leader,183 when the assignee is a squad). A plain reply to a *member's* comment does not fall back to the184 assignee. Any explicit mention — including of a member — cancels the fallback.185- **"A reply to a member's comment is safe" holds only when the root carries no agent mention.**186 A thread inherits its root: reply inside a discussion whose *root text* mentions an agent, and187 that agent is enqueued — even when both the root and your reply were written by a member, and188 even when your reply mentions nobody. Measured on 19/09/2026 (CLI v0.4.44): five replies by the189 same human to their own comments, under roots that named the Adversarial Reviewer, started five190 extra Reviewer runs and duplicated a whole review round. Before replying in a thread, read the191 root. To amend or complete a review request already posted, start the comment with `/note`; if192 it genuinely needs to wake someone, post a fresh top-level request with the right head and193 cancel the wrong run with `issue cancel-task <run-id>` first. Either way, confirm with194 `issue runs` afterwards — the queue, not your intent, is the record.195- **The assignee fallback fires in any status, closed issues included.** Comments are196 conversational and follow-up questions on finished work are expected behaviour. A terminal197 status is not a safe place to write.198- **A run is not idle just because its status is not `queued`, `running` or `pending`.**199 `waiting_local_directory` is a live state: the run holds a place in the queue waiting for the200 target repository's local checkout, and several runs against the same repository serialise201 behind it. Measured on 20/09/2026, asking three reviews on one repository at once: one ran and202 two sat in `waiting_local_directory` until it finished. A liveness check written as an203 allow-list of busy states reports them as idle — and "no run is alive" is exactly the204 precondition for merging. Decide liveness by a **deny-list of terminal states**205 (`completed`, `failed`, `cancelled`, …) and treat anything unrecognised as alive: an unknown206 status is far more likely to be a new busy state than a new finished one.207- It is skipped when the assignee has no runtime, is archived, you cannot invoke it, or it208 already holds a pending run on that issue — consecutive comments coalesce into the waiting run209 rather than starting a second one.210- `issue comment add` has **no `--no-start`**. That flag exists on `issue status`, `issue assign`211 and `issue update`, and nowhere else. Anything claiming otherwise — including a confident212 answer from a search engine — is wrong; `--help` settles it in one second.213214So the recipe for commenting on an agent-assigned issue without starting a run is a `/note`215prefix, not an unassign-comment-reassign dance. The dance works, but it mutates ownership for216the duration and is not needed.217218## 6. Platform limits worth knowing before you promise something219220- **Workspace isolation is real.** An agent running in one workspace cannot read another; only221 a human profile's CLI sees more than one. Cross-workspace search, dependencies and any222 portfolio view exist *only* through that CLI. When writing anything that governs agents, ask223 whether it assumes an agent can see a neighbouring workspace — if it does, that is a defect.224- **Agents cannot produce artifacts.** In an agent task the artifact tool is disabled and the225 refusal is explicit: `Artifact is disabled for this session, in subagents as well as here`.226 Delegating to a subagent does not work around it. Attach a file to a comment instead.227- **There is no MCP surface on the CLI** — but `agent update` takes `--mcp-config`,228 `--mcp-config-stdin` and `--mcp-config-file`, so agents *consume* MCP servers. The useful229 question is which servers your agents should have, not how to wrap the CLI in one. Pass that230 config by stdin or file: on the command line it lands in shell history and `ps`.231- `agent create --description` caps at 255 characters, and `--instructions` takes a string, not232 a path.233- Scheduled autopilots take a full cron expression and an IANA timezone234 (`autopilot trigger-add --kind schedule --cron … --timezone …`), and `autopilot create` takes235 `--subscriber`. `trigger-add --help` documents the `--timezone` default as UTC (v0.6.1,236 03/10/2026), so a cron written as the hour a person reads it lands hours off unless you pass237 the zone that person lives by: `--cron '0 9 * * 1' --timezone America/Sao_Paulo` for 09:00 on238 Mondays in Brasília. Sub-hourly expressions are writable; whether the server honours a given239 granularity is a test, not a promise.240241## 7. When a repository governs the board242243A team running Multica seriously keeps its agent instructions, workspace skills, workspace244context and project descriptions **versioned in a repository** and pushes them to the server245through the CLI. If `MULTICA_PLAYBOOK` is set, or the working tree looks like such a repo, that246repository outranks this skill and the reference on everything it declares.247248**Read before acting, in this order:** the repo's agent-context file (`CLAUDE.md` / `AGENTS.md`)249for the rules that bind you; the root `README` for what each directory is and which of them250deploy; the per-workspace manifest for ids; and the scripts directory for the drift check and251the deploy tool.252253The constraints such a repo almost always encodes — assume them until its own text says254otherwise:2552561. **Editing is not deploying.** A file in that repo is operational *text*; the live system257 changes only when `agent update`, `skill update`, `workspace update`, `project update` or258 `autopilot update` runs. A commit changes nothing on the server. Saying "the agent now does259 X" because the file says X, with no deployment, is a false statement about the system.2602. **Deployment is a human act.** Never run those five commands on your own. Propose the diff,261 name the file, and stop. If the repo ships a deploy script, its dry-run is yours to use and262 its apply mode is not.2633. **Ids come from the manifest, never from memory or from a listing you skimmed.** The264 manifest is generated from the server and diffable; that is the point of it. Read it by265 the key it actually uses: agents and skills are keyed by `name:`, projects and autopilots266 by **`title:`** — a `grep 'name: <project>'` finds nothing and says so, which is the good267 case; the bad case is reaching for a listing instead, or for memory.2684. **Measure drift before you claim state.** If the repo ships a drift check, run it and read269 its exit code as state, not as failure — "differs" is the normal condition before a270 deployment.2715. **A committed-but-undeployed change is tracked work, not a paragraph.** Register it wherever272 that repo says pending work lives — a board item, not a heading in a versioned file, which273 is how status silently goes stale.2746. **Text that governs other agents is not yours to change unilaterally.** Behavioural rules,275 status contracts, backlog policy and review thresholds are decisions of whoever owns the276 system. Propose in diff; a taken decision gets recorded where that repo records decisions.2777. **No credentials in any of that text.** Instructions are stored server-side and passed278 through process arguments.2798. **Shared text must not hardcode one workspace's ids.** A registry id from workspace A280 deployed into workspace B points at nothing, and the failure is silent. Render it from the281 manifest, or write the sentence without the id.282283Before writing anything into such a repo, ask yourself the two questions it exists to enforce:284does this change behaviour on the server (then it needs a deployment, tracked), and does it285assume an agent can see a workspace it cannot?286287## 8. Conduct on the board288289The reference covers the mechanics of side effects. These are the habits around them:290291- Scoping is a human gate. Promoting an item out of the unscoped column is where a person's292 decision is cheap and changes the outcome; leave it to them, and do not comment on an293 unscoped item — that comment is written to nobody.294- Acts performed with a human's profile are indistinguishable from that human in295 `issue timeline`. When a session acts, leave a dated note saying so, with the hour in the zone296 that person reads, the zone written out, and UTC beside it so the note can be matched against297 the API's stamps, which come in UTC: `18:41 BRT (21:41Z)`, not `18:41` and not `21:41Z` alone.298 When the UTC falls on another calendar day than the local hour, it carries its date, so the299 note is not matched against the wrong day: `22:59 BRT (04/10 01:59Z)`. The date is300 day/month, as a Brazilian reader writes it; a reader used to month/day (the US) would take301 `04/10` for 10 April. An hour with no zone cannot be placed against those stamps.302- Never create a registry object — agent, skill, project, autopilot — casually. It will appear303 in no manifest and no drift check will see it.304- **A write to the board never shares a command chain with a step that can fail.** Verify305 first — the id resolves, the file exists, the status is what you expect — and then write,306 as a command of its own. `|| true` on a probe is fine; `|| true` on the write, or a write307 that runs because the probe before it "succeeded" with garbage, is how a note lands on the308 wrong issue. In zsh, `set -e` does not cover a command substitution nor a Python heredoc:309 guard those with an explicit `|| exit 1`.310- **Before merging a PR that a human session conducted, read `issue runs <ID>` and311 `issue timeline <ID>` on the issue it closes.** An agent run may be alive on the same PR —312 a review round nobody asked for, a conductor about to merge — and two conductors on one PR313 is how a merge lands under the human's login with no record of who decided it. On314 18/09/2026 a human session merged a PR while the conductor agent was still running review315 rounds on it. The stage barrier woke the conductor 2 s after the merge — by the platform's316 own mention in a `system` comment, not by anyone's verdict; the review verdict landed 52 s317 after the merge and woke it again; it opened two follow-up issues at 150 s and 158 s, from318 a verdict that was no longer its to act on319 (measured at the source on 19/09/2026: the PR's `mergedAt`, `issue comment list` on the320 two issues involved, the issues' `created_at`).321- **`/note` writes without waking anyone, and that is all it does: it addresses nothing to322 anyone.** A pending item, a follow-up or a correction that lives only in a `/note` is323 written to nobody — the same failure as a comment on an unscoped item, from the other324 side. Anything that must be done goes where it will be found: a checkbox with a `verify:`325 in the issue description, or an issue of its own.326- **A description write replaces the whole field, and nothing merges it.** `issue update327 --description-*` writes the entire description; the CLI has no compare-and-set (no328 `--if-revision` as of v0.5.3 — `revision` comes back on read and cannot be passed on write).329 Two writers that read, edit and write back erase each other in silence, with no conflict and330 an ordinary `activity` event in the `timeline`. Measured on 21/09/2026 on LAS-69: a session331 marked ten DoD boxes at 16:39:04Z and another added two `verify:` criteria at 17:04:45Z, with332 two more description writes in between; nothing was lost only because of the order. The cost333 grows with the rule above — the more pending work lives as checkboxes in descriptions, the334 more a lost write costs. Three habits close most of the window: **read immediately before335 writing** (never write back a read from earlier in the turn); **change only your336 substring** — exact replacement asserted to occur once, or an append — instead of337 re-emitting an edited copy; and **check the window after writing**, which takes one check for338 each half of it. A write landing *after* yours shows in the content: re-read and compare with339 what you wrote — content, not `updated_at`, ignoring trailing whitespace (on 21/09/2026 a340 trailing newline from `print()` was enough for a false alarm on the first write, which is how341 a check gets abandoned). A write landing *before* yours was erased by yours, so the re-read342 shows your text and only the `timeline` shows it: count the `description_updated` events343 **before reading the description** (`N`) and again after writing (`M`); exactly one new event,344 and that one with your own id as its `actor_id`, means yours alone. Your id is your profile's345 (`user profile get`), except inside an agent task: there the write carries the agent's id,346 `MULTICA_AGENT_ID`, while `user profile get` returns the member who owns the token (v0.5.3,347 24/09/2026: task events on LAS-140 and LAS-141; the CLI sends the variable as `X-Agent-Id`).348 Wait for that one: an event by someone else showing first is not it. A writer with your id349 does look like you — another session on the same profile, the person it belongs to editing in350 the app (see above; not measured: which id an app edit carries), another run of the same351 agent — and while yours is late it passes for yours. The order is the point — a write landing352 between a read and a later count enters `N` while the text in hand is already stale. Measured353 on 24/09/2026 (v0.5.2, on a throwaway issue): every description write logged a354 `description_updated`, even one identical to the stored text, so a write that changes nothing355 must not be sent at all. Two shortcuts356 fail. `revision` also moves on a comment, a reply, a title or status change and on writes the357 `timeline` does not show (47 of 100 `lass` issues had more revisions than visible events on358 24/09/2026), so a jump is not proof of a description write. And `--since` drops the whole359 second it is given (v0.5.3, 24/09/2026, LAS-147: the event at 2026-09-21T20:07:03Z is missing360 from `--since 2026-09-21T20:07:03Z` and present from `--since 2026-09-21T20:07:02Z`), while an361 issue's `updated_at` is, as a rule, the second of362 its last event (96 of 100 `lass` issues on 24/09/2026) — so `--since <updated_at>` is blind to363 the very write that matters; to search by hand, start one second earlier. An erased write has364 nothing to be restored from: the event keeps no text (`details` is empty) and the CLI has no365 history command. Do not write over it again; its author — the event's `actor_type` and366 `actor_id` — re-applies it, and to an agent that request is a mention, which starts a run367 (§5). When that `actor_id` is your own id, the event does not say which of those writers made368 it: ask whoever runs them, which the `timeline` cannot answer. `scripts/patch-description.py`369 in this skill does all of it: it exits 1 without writing when a substring does not occur370 exactly once, an insertion (a replacement whose new text contains the old) or the append is371 already there, or the edits change nothing — so a re-run after an exit 3 writes nothing if an372 edit survived; 2 on `--edits` that are not pairs of two strings, or an empty append; and 3373 when the re-read differs, there is not exactly one new event, or none by your id, printing the374 read's `updated_at`, `revision` before and after, each new event with its author (yours375 marked), and the command that lists them.