multica-squads

Multica スクワッド

クイックスタート

スクワッドが実行されたか、されなかったかの理由をデバッグする場合は、まず次を確認してください:

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

この 2 つのコメント読み取りは一連の流れです。まずルートをスキャンし、その後に重要そうなスレッドを開きます — メンションのトリガー、失敗理由、ユーザーからの指示は通常返信の中にあり、ルートのスキャンでは返されません。

コマンドの形式が不明な場合は、推測せずにヘルプを確認してください:

multica squad --help
multica squad member --help
multica issue update --help
multica issue comment add --help

テストのためだけに、スクワッドのアサイン、コメント、メンション、更新、削除、アクティビティの記録を行わないでください。これらはワークスペースの状態を変更したり、エージェントの実行をトリガーしたりする可能性があります。

コアモデル

Multica のスクワッドは、ワークスペースのルーティングと調整のためのオブジェクトです。

スクワッドはエージェントではありません。それ自体では作業を実行しません。現在の動作: スクワッドにルーティングされた作業は、スクワッドの leader_id エージェントを通じて実行されます。

重要な帰結:

• イシューをスクワッドにアサインすると、リーダーにルーティングされます;
• スクワッドにメンションすると、リーダーにルーティングされます;
• スクワッドにアサインされたオートパイロットは、リーダーに解決されます;
• スクワッドのメンバーは自動的にファンアウトされません;
• スクワッドの instructions はリーダーへのブリーフィング内容であり、メンバーへのプロンプトではありません。

CLI

スクワッドのコマンド:

multica squad list --output json
multica squad get <squad-id> --output json
multica squad create --name <name> --leader <agent-name-or-id> --output json
multica squad update <squad-id> --instructions "<leader coordination policy>" --output json
multica squad delete <squad-id>

メンバーのコマンド:

multica squad member list <squad-id> --output json
multica squad member add <squad-id> --member-id <id> --type agent|member --role <role> --output json
multica squad member remove <squad-id> --member-id <id> --type agent|member
multica squad member set-role <squad-id> --member-id <id> --member-type agent|member --role <role> --output json

スクワッドリーダーの評価コマンド:

multica squad activity <issue-id> action|no_action|failed --reason "<why>" --output json

activity は書き込みです: イシューに対するリーダーの評価決定を記録します。トリガーを評価した後、スクワッドリーダーとして行動する場合にのみ使用してください。

どのイシューを受け付けるか: 現在のターンが実行されているイシューです。対象のイシューは、あなたのスクワッドにアサインされている必要はありません — 個々のエージェントが所有するイシューへの @squad メンションや、子イシューに紐づけられたリーダータスクでも、問題なく記録できます。サーバーが確認するのはあなたのタスク行 (is_leader_task とスタンプされた squad_id) であり、イシューの担当者ではありません。ステージバリアによって起動されたリーダーは親イシュー上で実行されるため、たった今読んだ子イシューではなく親イシューに対して記録してください。無関係なイシュー ID を渡すと拒否され、エラーには使用すべきだったイシューが示されます。

呼び出しが失敗した場合は、黙って終了しないでください — no_action に対するコメント禁止は、記録が成功した後にのみ適用されます。代わりに、結果を短いコメントとして 1 件投稿してください。ただし、このターンでまだコメントしていない場合に限ります: action の経路では、あなたの委任コメントがすでにその記録となります。

スクワッドでしばしば必要となるイシュー/コメントのコマンド:

multica issue get <issue-id> --output json
multica issue update <issue-id> --help
multica issue comment list <issue-id> --roots-only --summary --output json
multica issue comment add <issue-id> --help

コメントの読み取りは範囲を限定したままにします — 上記のクイックスタートにあるスキャンしてから展開する流れであり、無制限の issue comment list の一括取得は決して行いません。

読み取りには --output json を推奨します。書き込みの前に --help を使用してください。

スクワッドのフィールド

• id — スクワッドの UUID。
• workspace_id — スクワッドが属するワークスペース。
• name — 表示名。ワークスペースごとに一意です。
• description — 人間向けのメタデータ/表示テキスト。ソースが消費者を証明しない限り、実行時のプロンプトへの影響を想定しないでください。
• instructions — スクワッドリーダーのブリーフィングに追加されるスクワッドレベルの指示。すべてのスクワッドメンバーに直接注入されるわけではありません。
• avatar_url — 省略可能なスクワッドのアバター URL。
• leader_id — スクワッドリーダーのエージェント ID。スクワッドにルーティングされた作業の実行時ターゲットです。
• creator_id — スクワッドの作成者。
• archived_at / archived_by — アーカイブのメタデータ。アーカイブされたスクワッドは、アサイン/オートパイロットのルーティング経路で拒否されます。
• member_count — スクワッドメンバーのリスト応答の件数。
• member_preview — スクワッドメンバーのリスト応答のプレビュー。

instructions は、リーダー向けの調整ポリシーに使用してください: スクワッドの責務、委任の期待事項、いつ人間に尋ねるか、レビュー/ハンドオフのルールなどです。すべてのメンバーが自動的に受け取るかのように書かないでください。

スクワッドメンバーのフィールド

• member_type — agent または member。
• member_id — エージェントまたはワークスペースメンバーの ID。
• role — 名簿のロールラベル。現在の動作: 空でない role はリーダーのブリーフィング名簿に表示されます。スケジューリング、権限、ルーティングの動作を生み出すと想定しないでください。

作成とリーダーメンバーシップ

スクワッドの作成には leader_id が必要です。リーダーはワークスペースのエージェントでなければなりません。 作成/更新ではアーカイブされたリーダーは拒否されません。検索はエージェントがワークスペースに存在することだけを確認します。アーカイブされたリーダーは、後段のルーティング/ディスパッチでフェイルクローズします。割り当て、オートパイロットの受け入れ、コメント/メンションの準備ゲートはすべて、タスクがエンキューされる前にアーカイブされたリーダーを拒否します。

作成時、バックエンドはリーダーをロール leader のスクワッドメンバーとして追加しようと試みます。leader_id を更新する際に、新しいリーダーがまだメンバーでない場合、バックエンドは新しいリーダーをロール leader のスクワッドメンバーとして追加します。

リーダーブリーフィング

スクワッドリーダーのタスクでは、Multica はリーダーエージェントの指示にスクワッドリーダーブリーフィングを追記します。ブリーフィングには以下が含まれます:

• スクワッド運用プロトコル;
• スクワッド名簿;
• スクワッド指示。ただし instructions が空でない場合のみ。

名簿のエントリには、メンバー名、メンバータイプ、メンションの Markdown、および空でないロールが含まれます。エージェントメンバーの場合、名簿には割り当てられたスキルも記載されます(skills: a, b、エージェントにスキルがない場合は no skills assigned)。これにより、リーダーはロールのラベルから推測するのではなく、能力に基づいて委任できます。人間のメンバーにはスキルのセグメントはありません。組み込みの multica-* スキルは記載されません — エージェントに明示的にアタッチされたワークスペーススキルのみです。アーカイブされたエージェントメンバーはブリーフィングの名簿からスキップされます。

イシューの割り当て動作

イシューは以下でスクワッドに割り当てることができます:

assignee_type = "squad"
assignee_id = <squad-id>

現在の動作:

• 割り当ては作業を squad.leader_id にルーティングします;
• すべてのスクワッドメンバーをエンキューするわけではありません;
• ステータスが backlog の間の割り当ては、作業を即座に開始しません;
• スクワッドに割り当てられたイシューを backlog から移動すると、リーダーをトリガーできます;
• 担当者を変更すると、新しい担当者パスをエンキューする前に、そのイシューの既存のタスクがキャンセルされます;
• 親イシューのステータスはエージェント管理です(直接エージェント割り当てと同じモデル): リーダーの最初の割り当てターンで親を in_progress に移動し、メンバーが作業している間はそこに保ちます。リーダーは、後続の再トリガーで全体の目標が達成されたことが確認された場合にのみ、親を in_review に移動します。リーダーの task の完了(最初のディスパッチを含む)自体は、イシューのステータスを変更しません;
• そのステータス権限は、イシューの assignee_type / assignee_id がこのスクワッドを指している場合にのみ付与されます。リーダーブリーフィングは、プレーンなエージェントが所有するイシューへの @squad メンションを含む、すべてのリーダーパスで注入されます — それらのパスでは、プロトコルは代わりに「このイシューのステータスを変更しないでください」を明示的に含みます。

上記のステータス名はカテゴリのルールです: ワークスペースは組み込み以外のカスタムステータスを定義でき、各ステータスはそのカテゴリの動作を完全に継承します(ワークスペースカタログが存在する場合、ランタイムブリーフにそれが記載されます)。

割り当ての検証は、存在しない type/id のペア、存在しないスクワッド、アーカイブされたスクワッド、アーカイブされたリーダー、およびアクターがアクセスできないプライベートリーダーを拒否します。

コメントとメンションの動作

イシューがスクワッドに割り当てられている場合、新しいコメントでスクワッドリーダーを起こすことができます。これはリーダールーティングであり、メンバーへのファンアウトではありません。

スクワッドメンションの形式:

[@Squad Name](mention://squad/<squad-id>)

現在の動作: スクワッドを解決し、leader_id を読み取り、リーダータスクをエンキューし、現在のコメントをトリガーコメントとして使用します。すべてのスクワッドメンバーをエンキューするわけではありません。

オートパイロットの動作

オートパイロットはスクワッドに割り当てることができます。assignee_type = "squad" の場合:

• 実行可能なエージェントは squad.leader_id から解決されます;
• 受け入れ/準備チェックはリーダーに対して実行されます;
• アーカイブされたスクワッドはフェイルクローズ/ディスパッチをスキップします;
• 実行の帰属は、該当する場合にスクワッド ID を記録します。

create_issue オートパイロットの場合、作成されたイシューは assignee_type = "squad" と assignee_id = <squad-id> を保持しますが、実際に実行するエージェントは解決されたリーダーです。run_only オートパイロットの場合、イシューは作成されません。タスクは解決されたリーダーエージェントに対して直接作成されます。

苦情や製品ギャップへの対応

ユーザーが squad の動作について、誤っている、わかりにくい、期待外れだと言及した場合、すぐにコードが壊れていると決めつけてはいけませんし、現状の動作が存在するという理由だけでそれを擁護してもいけません。まず分類してください：

• 現在の動作として想定どおり；
• 設定の問題；
• 製品上の制限；
• 実際のバグ。

現在のソースに基づく動作を説明してください。その動作が技術的には正しくても、製品として望ましくない場合は、その旨を伝え、範囲を限定した製品/コードの変更を提案してください。

確認なしに squad のルーティング、メンバーへのファンアウト、リーダーへのブリーフィング、自動操縦の動作、コメントトリガーの動作を暗黙に変更しないでください。これらは副作用を伴う製品契約の変更です。

副作用

以下の操作はエージェントの作業を起動したり、永続的な状態を変更したりする可能性があります：

• squad の作成；
• squad のフィールドの更新；
• leader_id の変更；
• メンバーの追加/削除；
• メンバーのロールの変更；
• イシューを squad に割り当てる；
• squad に割り当てられたイシューをバックログから移動する；
• squad に割り当てられたイシューにコメントする；
• squad にメンションする；
• squad に割り当てられた自動操縦を作成または起動する；
• multica squad activity で squad のアクティビティを記録する；
• squad を削除/アーカイブする。

ユーザーが明示的に許可しない限り、テストとして副作用のある操作を実行しないでください。

よくある誤った想定

• squad はエージェントではありません。
• squad の作業は leader_id にルーティングされ、すべてのメンバーにではありません。
• squad のメンションはリーダーにルーティングされ、すべてのメンバーにではありません。
• squad の割り当てはリーダーにルーティングされ、すべてのメンバーにではありません。
• squad の自動操縦は、実行可能なエージェントとしてリーダーに解決されます。
• instructions はリーダーへのブリーフィング内容であり、メンバーへの自動プロンプトではありません。
• description が実行時プロンプトの内容であることは証明されていません。
• role は名簿のコンテキストであり、自動スケジューリングではありません。
• バックログへの割り当ては、すぐに作業を開始するわけではありません。
• 最初のリーダーへのディスパッチは親の完了ではありません — リーダーが後に全体の目標を確認し、それを in_review に移すまで、親は in_progress のままです。
• 子イシューが完了しても、サーバーが自動的に親のステータスを切り替えることはありません。明示的な要求（まとめる際の in_review を含む）とともにリーダーを起こすだけです。
• リーダーへのブリーフィングを受け取ったからといって、ステータスの権限があるわけではありません。他の人に割り当てられたイシューに squad が @ メンションされた場合はゲストです：名簿と委任のルールは適用されますが、multica issue status は適用されません。

参照

ソースパス、テスト、エッジケース、正確なルーティングの詳細については、以下を参照してください：

references/squad-source-map.md