multica-cli

Multica CLI

ローカルの multica CLI を信頼できる情報源として使用してください。このスキルでは、外部エージェントが Multica を安全に操作する方法を説明しますが、権限を付与するものではありません。権限は、ユーザーがインストールした CLI、選択されたプロファイル、ワークスペース、およびコマンド実行に対する明示的な承認によってのみ決まります。

安全に開始する

1. 作業を始める前に、CLI とアカウントの状態を確認します。

multica version
multica auth status
multica config show

このスキルには multica v0.4.26 以降が必要です。 使用するコマンドのうち、特に issue status／assign／update の --no-start は、それより前のバージョンには存在せず、古い CLI では拒否されます。multica version が 0.4.26 未満を示す場合は、存在しないフラグを回避して作業するのではなく、停止してユーザーにアップグレードを依頼してください（brew upgrade multica-ai/tap/multica または multica update）。

multica auth status で有効なセッションがないと表示された場合、CLI はログインしていません。停止してユーザーに認証を依頼してください。認証情報を偽装しようとしてはいけません。

multica login        # interactive auth + workspace setup
multica setup        # alternative: configure CLI, authenticate, start daemon

2. 適切なワークスペースとプロファイルを使用します。利用可能なものを確認し、ユーザーが指定した場合は明示的なフラグを優先してください。

multica workspace list --output json                 # which workspaces exist
multica workspace switch <workspace-id>              # set the default for this profile
multica --profile <profile> --workspace-id <workspace-id> issue list --output json

3. コマンドが対応している場合は、--output json を優先してください。テーブルをスクレイピングするのではなく、JSON を解析します。

4. トークン、Cookie、API キー、CLI 設定のシークレットを公開したり保存したりしてはいけません。プライベート HTTP API を直接呼び出して、ワークスペースの権限を回避してはいけません。

コマンドリファレンス

以下のフラグは、最もよく使用する課題ワークフローで一般的なものです。これらについて --help を実行する必要はありません。拒否されたフラグの確認や、ここでは形式を網羅していない、形が異なる長尾の名前空間の調査が必要な場合にのみ --help を実行してください。[ ] は省略可能なフラグ、| は相互排他的なフラグを示します。

# Read
multica issue get <id> --output json
multica issue list [--status <s>] [--assignee <name> | --assignee-id <uuid>] [--project <id>] [--priority <p>] [--metadata key=value] [--sort <col>] [--direction asc] [--limit N] [--offset N] --output json
multica issue search <query> [--include-closed] [--limit N] --output json
multica issue children <id> --output json
multica issue pull-requests <id> --output json
multica issue metadata list <id> --output json

# Comments (read) — see Reading Comments below before picking a mode
multica issue comment list <id> --roots-only --summary --compact --output json   # scan threads cheaply
multica issue comment list <id> --thread <comment-id> --tail 30 --compact --output json  # open one thread
multica issue comment list <id> --recent N --compact --output json               # N most active threads
#   also: --since <RFC3339>, --full (unfold resolved threads),
#         --before/--before-id <cursor> for pagination

# Create / update
multica issue create --title "..." [--description-file <path>] [--priority <p>] [--status <s>] [--assignee <name> | --assignee-id <uuid>] [--parent <id>] [--stage N] [--project <id>] [--due-date YYYY-MM-DD] [--start-date YYYY-MM-DD] [--attachment <path>] [--attachment-id <uuid>] [--allow-duplicate] --output json
multica issue update <id> [--title "..."] [--description-file <path>] [--status <s>] [--priority <p>] [--assignee <name> | --assignee-id <uuid>] [--parent <id> | --parent ""] [--stage N] [--due-date YYYY-MM-DD] [--start-date YYYY-MM-DD] [--no-start]

# Status / assignment  (status values: backlog | todo | in_progress | in_review | done | blocked | cancelled)
multica issue status <id> <status> [--no-start]
multica issue assign <id> --to <name> | --to-id <uuid> | --unassign [--no-start]

# Comment (write) — body always via file, see Write Workflow below
# --parent is required when a comment triggered your task; see Issue Comments
multica issue comment add <id> [--parent <comment-id>] --content-file <path> [--attachment <path>]

# Metadata
multica issue metadata set <id> --key <k> --value <v> [--type string|number|bool]
multica issue metadata delete <id> --key <k>

# Labels — issue label add/remove take a label UUID, so list the workspace labels first
multica label list --output json
multica issue label list <issue-id> --output json
multica issue label add <issue-id> <label-id>
multica issue label remove <issue-id> <label-id>

# Custom properties (workspace-defined fields)
multica property list --output json
multica issue property list <issue-id> --output json
multica issue property set <issue-id> --name <name> --value <v>
multica issue property unset <issue-id> --name <name>

# Subscribers (who gets notified; defaults to the caller)
multica issue subscriber list <issue-id> --output json
multica issue subscriber add <issue-id> [--user <name> | --user-id <uuid>]
multica issue subscriber remove <issue-id> [--user <name> | --user-id <uuid>]

# Runs — see Inspecting Runs below
multica issue runs <issue-id> --output json
multica issue run-messages <task-id> [--issue <issue-id>] [--since N] --output json
multica issue usage <issue-id> --output json
multica issue rerun <id> --output json
multica issue cancel-task <task-id> [--issue <issue-id>]

issue assign では --to／--to-id を使用しますが、issue create／issue update では --assignee／--assignee-id を使用する点に注意してください。

ほかの名前空間も同じ形式です。タスクで必要になったら確認してください。

multica project --help
multica agent --help
multica squad --help
multica runtime --help
multica repo --help
multica skill --help
multica autopilot --help
multica attachment --help
multica label --help
multica property --help
multica chat --help
multica user --help

コメントを読む

コメント履歴は、読む際に最も多くのトークンを消費するものであり、読み取りモードは相互に置き換えられません。

• --recent N が上限とするのはコメント数ではなくスレッド数で、各スレッドにはすべての子孫が含まれます。課題のルートスレッドが N 個未満の場合、履歴全体が返されます。これは低コストの読み取りではありません。
• 2 回に分けて範囲を限定して読み取ることを優先してください。まず --roots-only --summary で一覧を確認します（各ルートには reply_count と last_activity_at も表示されます）。次に、重要なスレッドだけを --thread <id> --tail N で開きます。
• JSON の読み取りには --compact を追加してください。内容は変更せず、エコーされたフィールド、null フィールド、管理用フィールドを省略します。エージェントによる読み取りでは、常に適切です。
• 解決済みのスレッドはデフォルトで折りたたまれます。 完全なスレッドを取得するモードでは、解決済みのスレッドはルートと結論にまとめられ、削除された件数がルートに表示されます。これはデータの消失ではありません。解決済みの議論が実際に必要な場合は、--full を指定してください。

multica issue comment list <issue-id> --roots-only --summary --compact --output json
multica issue comment list <issue-id> --thread <comment-id> --tail 30 --compact --output json

項目を検索する

multica issue search はタイトル、説明、コメント本文を検索するため、スレッド内でしか扱われなかった決定事項も見つけられます。存在しないと判断する前に、まず検索してください。

multica issue search "retry backoff" --include-closed --output json
multica issue list --metadata pr_number=123 --output json

数字だけのクエリや識別子の形式をしたクエリ（412、AGE-412）は、その番号の課題に一致します。また、プレフィックスの検証は行われません。別のトラッカーから識別子を貼り付けると、無関係なローカルの課題が一覧の先頭に表示される場合があります。match_source フィールドは表示用のヒントであり、フィルターではありません。

書き込みワークフロー

書き込みには副作用があるものとして扱ってください。ユーザーが書き込みを明確に依頼していない場合は、実行前に確認してください。これには、コメントや課題の作成、ステータスの変更、割り当て、再実行、キャンセル、ラベルやプロパティの変更、エージェントへのメンション、スクワッドへのメンション、Webhook／自動操縦の変更、リポジトリのチェックアウト操作が含まれます。

ファイルパスは作業ディレクトリ内に置く必要があります

--content-file、--description-file、--attachment では、現在の作業ディレクトリ外のパスは拒否されます。これは意図的な仕様です。別の実行環境や実行時の古いファイルが、気づかないうちに使われるのを防ぎます。作業中のディレクトリ内にファイルを作成してください。/tmp や共有パスには作成しないでください。そうしないとコマンドは失敗します。

# correct: relative to the working directory
multica issue comment add <issue-id> --parent <comment-id> --content-file ./reply.md

--allow-external-file を使うと、このチェックを回避できます。ユーザーがその特定の外部パスを指定した場合に限って使用してください。原因を特定できていない失敗を回避するために使ってはいけません。

イシューのコメント

エージェントが作成するコメントは、必ず本文を UTF-8 ファイルに書き込み、--content-file で渡してください。構造化されたコメントにインラインの --content を使わないでください。シェルによって、バッククォート、$() 式、変数、引用符、改行が CLI に渡される前に書き換えられることがあります。

# Create reply.md with real newlines first, then:
multica issue comment add <issue-id> --parent <comment-id> --content-file ./reply.md
rm ./reply.md

--parent は条件付きで指定するもので、常に必要なわけではありません。コメントがきっかけでタスクが開始された場合は必須です。そのようなタスクからのトップレベルコメントはサーバーに拒否されます。また、その値には返信対象のコメントを指定する必要があります。イシューで新たにトップレベルの議論を始める場合は、省略してください。フラグを満たすためだけに、無関係なスレッドに返信を付けてはいけません。

改行を偽装するために、リテラルな \n エスケープを書き込まないでください。

イシューとメタデータ

長いイシューの説明にはファイルを使用してください。

multica issue create --title "..." --description-file ./description.md
multica issue update <issue-id> --description-file ./description.md

issue create は、対応中の重複イシューがある場合、新しいイシューの作成を拒否します。反射的に --allow-duplicate を付けて再試行しないでください。まず既存のイシューを読み、ユーザーが本当に 2 件目を必要としていることを確認してください。

メタデータはログではなく、イシューに紐づく永続的な状態です。作業開始時に読み取ってください。ただし、今後の実行でも再確認する価値のある重要度の高い事実に限って書き込みます。たとえば、pr_url、pr_number、pipeline_status、deploy_url、external_issue_url、waiting_on、blocked_reason、decision などです。

multica issue metadata set <issue-id> --key pr_url --value <url>
multica issue metadata delete <issue-id> --key stale_key

メタデータは、イシューごとに自由形式で設定できる KV です。カスタムのプロパティは別のもので、ワークスペース全体で共有される、ワークスペース定義の型付きフィールドです。定義の作成やアーカイブは管理者レベルの変更となるため、値は設定しても、依頼されない限り定義は変更しないでください。

--no-start によるエージェント実行の抑制

デフォルトでは、issue status、issue assign、issue update によって新しいエージェント実行がキューに追加されることがあります。これにより作業が引き継がれます。すでに進行中の作業について、担当者や進捗を記録するだけの場合は、追加の実行は無駄なコストとなり、重複した作業者を生み出します。

multica issue status <id> in_progress --no-start
multica issue assign <id> --to <name> --no-start
multica issue update <id> --status in_review --no-start

目安：新しい作業を誰かに引き渡す場合は省略し、すでに進行中の作業を記録する場合は --no-start を指定します。

メンションによる副作用

メンションリンクは飾りではなく、アクションを実行します。

[@Name](mention://agent/<agent-id>)     # enqueues that agent
[@Name](mention://squad/<squad-id>)     # enqueues the squad leader
[@Name](mention://member/<user-id>)     # NOTIFIES that person
[@all](mention://all/all)               # broadcasts to the workspace
[MUL-123](mention://issue/<issue-id>)   # renders an issue link
[Name](mention://project/<project-id>)  # renders a project link

このうち 3 種類は、相手に影響します。agent と squad はコストのかかるエージェント作業をキューに追加し、member は人に通知し、@all はワークスペース全体に通知します。自由に使える単なるリンクは issue と project だけです。

メンションを作成する前に、JSON 出力で正しい UUID を確認してください。

multica agent list --output json
multica squad list --output json
multica workspace member list --output json

感謝、了承、締めくくりのためだけにエージェントをメンションしないでください。返信でエージェントを再度メンションすると、別の実行が起動し、ループが発生することがあります。人に対しても同じように慎重にしてください。礼儀としてではなく、対応が必要な場合にメンバーをメンションします。

ステータスと割り当てによる副作用

ステータスの変更は見た目だけのものではありません。作業を開始したり、停止したりすることがあります。

• backlog にすると、エージェントが割り当てられたイシューは保留になります。
• backlog から todo または別の進行中ステータスに変更すると、担当者の作業がキューに追加されることがあります。
• done と cancelled は終端状態です。
• PR や人によるレビューを待つ間は in_review が便利ですが、これも書き込みを伴います。
• これらはいずれも、実行を開始せずに記録できます。上記の --no-start を参照してください。

順序が決まった作業のサブイシューを作成する場合は、後の手順にステージと backlog を使用します。ステージ内のすべてのサブイシューが完了したときにのみ、親イシューの担当者が起動されます。

multica issue create --title "Research" --parent <id> --assignee <agent> --stage 1 --status todo
multica issue create --title "Build" --parent <id> --assignee <agent> --stage 2 --status backlog
multica issue children <id> --output json

実行履歴の確認

課題が行き詰まっているように見える場合や、結果が分かりにくい場合は、コメントから推測するのではなく、実行履歴を確認してください。

multica issue runs <issue-id> --output json                       # what ran, and how it ended
multica issue run-messages <task-id> --issue <issue-id> --output json  # what that run actually did
multica issue usage <issue-id> --output json                      # aggregated token cost

--issue を使うと、完全な UUID の代わりに短いタスク ID のプレフィックスを指定できます。

次の 2 つの操作は実際に影響が大きいため、どちらも事前にユーザーに確認してください。

multica issue rerun <id> --output json          # re-enqueue the current assignment as a new task
multica issue cancel-task <task-id> --issue <issue-id>   # interrupt a running agent mid-flight

cancel-task は実行中のエージェントを中断するため、進行中の作業は失われます。まだ確認していない状態を「片付ける」ために実行してはいけません。

プルリクエスト

Multica の課題に対してコードを変更した場合は、Multica が課題をリンクできるように、ルーティング可能な課題キーを PR のタイトル、本文、またはブランチに含めてください。

MUL-123: fix login redirect

PR をマージすると課題をクローズする場合に限り、クローズの意図を指定してください。

Closes MUL-123
Fixes MUL-123
Resolves MUL-123

リンクされた PR の状態は、GitHub の検索やメタデータから推測せず、Multica で確認してください。

multica issue pull-requests <issue-id> --output json

CLI で実行できない場合

CLI ですべての Multica の機能を利用できるわけではありません。必要なコマンドが存在しない場合は、その旨を明確に伝え、該当する手順を示したうえで、完了するには Multica Web を使うよう案内してください。部分的な実行を完了したかのように見せてはいけません。また、不足を補うために curl や非公開の HTTP API を使ってはいけません。

実際に起きたことを報告してください。実行したコマンド、成功したコマンド、ユーザーに残されている作業を伝えてください。拒否または失敗したコマンドも報告すべき結果であり、別の方法で回避すべき問題ではありません。

外部エージェントとの境界

外部エージェントには、Multica の実行時コンテキストが自動的に渡されません。特定の課題またはコメントについて作業するようユーザーから依頼された場合は、次の情報を確認するか、特定してください。

• 課題 ID または課題キー
• 返信する場合は、トリガーとなったコメント ID と親スレッド
• 複数のワークスペース／プロファイルが設定されている場合は、使用するワークスペース／プロファイル
• 書き込みが許可されているかどうか
• メンション、ステータス変更、再実行、割り当てが許可されているかどうか

これらの情報が不足しており、操作によって状態が変更される場合は、先に確認してください。読み取り専用の調査では、JSON 出力でコンテキストを収集し、ほかに必要な情報を報告してください。