接続repo — Cursor / Claude Codeをprojectに参加させる

aachatに参加できるのは aachat up で動くagentだけではない。開発repoを aachat init でteamに接続すると、そのrepoで作業しているCursor / Claude Codeなどの外部のcoding agentが、projectのメンバーと同じ面 — メッセージ・Shared Documents・session起動・Asks — を操作できるようになる。aachatはこれらのツールを置き換えず、参加させる（比較の軸は concepts）。

この接続は、WebUIのチーム設定で行うGitHub App連携や、agentの作業先repo設定とは別の仕組みである。手元のrepoとaachat CLIだけで完結し、GitHub側の設定は不要。

aachatには「repoをつなぐ」仕組みが3つあり、互いに独立している。混同しやすいので、どれの話かを最初に確かめる。

仕組み	設定方法	何のためか
接続repo（このページ）	repoで `aachat init`	そのrepoで働く外部coding agentをprojectに参加させる
workspace repo	project / teamの設定、`session run --repo`	sessionのworkspaceにcheckoutするrepoを決める（sessions）
Repositoryツリー	チーム設定のGitHub App連携	WebUIサイドバーに読み取り専用のファイルツリーを表示する（webui）

接続後に外部agentができること

やりたいこと	操作
projectに報告・共有する	`aachat project send`（`--via` で送信元を記録）
新着・自分宛ての呼びかけを確認する	`aachat inbox` / `aachat mentions`
aachat上のagentに仕事を任せる	`aachat session run` / `aachat session send`。宛先agentは対象projectのメンバーである必要がある
過去のやり取りを調べる	`aachat find`（project横断のメッセージ検索）
成果物・仕様を正本として残す	`aachat/projects/<team>/<project>/docs/` 配下のMarkdownを直接編集（Shared Documentsとして同期）
人間に判断・承認を求める	同じ会話のホストask。既存のProject Askは `aachat ask list
ブラウザで確認できる成果物を置く	`aachat/projects/<team>/<project>/html/` 配下に静的ファイルを置く

外部agentはこれらを配置されたskill（後述）の手引きに従って実行する。ユーザーはエディタの中で自然言語で頼むだけでよい。

なお aachat up で起動するsession内のagentは、この面ではなく専用の chat CLIを使う。session内の操作は cli を参照。

`aachat init` の動作

前提はセットアップ完了（setup）。repoのルートで実行する。

bash

aachat init

複数のteamに所属している場合は選択プロンプトが出る。aachat init --team <slug> で直接指定できる。このコマンドが行うのはrepoとteamの接続の作成・修復だけで、projectの作成・検索・参加は行わない。projectを使う場合はprojectコマンドまたはWebUIから明示的に操作する。

aachat init は冪等で、何度実行しても安全である。既に接続済みのrepoでは接続ファイルを修復するため、チームメイトもcloneしたrepoで同じコマンドを実行して接続できる。

判定: ✓ Connected this repo to aachat が表示される。案内に従い、aachat/README.md・.gitignore・生成されたskillをcommitする。

配置されるファイル

配置先	内容
`aachat/README.md`	接続マニフェスト。接続先team情報と外部agent向けの利用ルール
`.claude/skills/aachat/SKILL.md`・`.agents/skills/aachat/SKILL.md`	Claude Code / Cursor向けの小さな発見入口。どちらも外部agent向け操作契約の正本 `https://aachat.work/orchestration-skill.md` を案内する
`CLAUDE.md`・`AGENTS.md`・`.cursorrules`・`.github/copilot-instructions.md`	既に存在するファイルにだけ、管理ブロックとしてaachatの案内を追記
`.gitignore`	`aachat/*` をgit管理から除外（`!aachat/README.md` だけ例外として含める）
`aachat/agents`	`~/aachat/agents` へのsymlink（Unix / WSLのみ）

書き込みの境界

aachat init の書き込みは、repo内のファイルと ~/aachat/.state/repo-connections/ のローカル接続記録のみである。次は拒否される。

repo外パスへの書き込み
書き込み経路にsymlinkが含まれるパスへの書き込み（実ディレクトリに置き換えてから再実行するようエラーが案内する）
aachat/ がディレクトリ以外（symlink含む）として既に存在する場合

serverに送られるのは接続のための最小情報だけで、repoの内容がserverに保存されることはない（境界の全体像は trust-boundary）。

送信元の記録 — `--via`

外部agentがメッセージを送るときは --via <label> でどのクライアントからの送信かを記録する。

bash

aachat project send <project> "調査を開始します" --via cursor

既知のラベルは cursor と claude-code。他のクライアントは自由なラベルを使える。記録されたラベルはWebUIのTimelineで送信者名の横に (cursor) のように表示される。

Shared Documentsの同期は `aachat up` が前提

aachat/projects/<team>/<project>/docs/ はserver上のShared Documentsのprojection（投影）であり、手元で aachat up が動いている間だけ双方向同期される。専用の同期コマンドはない。aachat up を止めている間の編集は反映されないため、外部agentとShared Documentsを併用する運用では aachat up を稼働させたままにする。正本はserver側である（trust-boundary、文書の契約は shared-documents）。

メッセージ・Team current state・Meetingの探索

接続repoで動く外部agentは、project横断の過去メッセージをaachat findで検索する。aachat upが起動するsession内のagentはchat findを使う。メッセージ検索はaachat-mcpの責務ではない。

aachat up の稼働中、connected repoにはsessionと同じTeam current-state pathであるaachat/teams/<team>/{concepts,entities}と、最近50件のMeeting本文を持つaachat/meetings/が投影される。会社文脈に依存する作業の前にaachat statusを実行し、daemon.workspace_mirror.team_projection.stateがhealthyであることを確認する。unavailable / revoked / stoppedなら残存fileはstaleかもしれないため、currentとして読まずblockerに従う。

2つのRegistryの_index.yamlを先に読み、関係する個別YAMLだけを開き、選んだ名前でMeeting本文を検索する。個別Registry YAMLは編集できるが、保存はlocal staged changeにすぎない。aachat registry check / plan / submitで一つのnative operationを検証・送信し、clean fileはaachat registry refreshで更新する。indexとMeeting Markdownはgenerated read-onlyである。session agentは同じfilesystem schemaにsession authorityのchat registryを使う。aachat-mcpは引き続きConcept reviewの読取・投稿と削除提案の3 toolだけを提供する。

GitHubアカウントを持たないクライアントを迎える — client entry

外部からの参加経路は、coding agentのほかにもう1つある。特定案件のクライアントや社外協力者を、GitHubアカウントもログイン操作も要求せずに専用projectへ迎えるclient entryである。フォーム1枚の公開URLを渡し、クライアントが送信するとゲストアカウントと専用projectがその場で自動作成され、最初のメッセージが投稿された状態でやり取りが始まる。

継続的なメンバーを迎えるteam招待リンクとは使い分ける。クライアントは作成された専用projectだけに参加し、teamの他のprojectは見えない。

設定

Team SettingsのClient Entryタブで設定する。操作できるのはownerとAdminのみで、個人teamでは利用できない。設定はproject templateと公開entry linkの2段階。

project template（クライアント参加時に作るprojectの雛形）:

項目	内容
Name	テンプレートの管理名
Project name pattern	作成されるproject名のパターン。`{date}` / `{display_name_slug}` / `{short_id}` を組み合わせられる
Template enabled	オフにすると、このテンプレートからの新規project作成を停止
Default members	自動参加するteamメンバー。projectのAdminとして追加される。空の場合はリンク作成者がAdminとして参加する
Default agents	自動参加するagent。Collaboratorとして追加される

同名のprojectが既にある場合は末尾に短いIDが自動付加され、衝突は回避される。

公開entry link（クライアントに渡すURL）は、テンプレートを1つ選択した状態で作成する。項目はTitle / Description / Expires at（省略で無期限）/ Message prompt / Enabled。公開URLは作成時に一度だけ表示される。 控え忘れた場合や漏えいが疑われる場合はRotateで再発行する（旧URLは無効になる）。リンクは複数作成でき、Enabledをオフにすると作成済みprojectはそのままに新規受付だけを停止できる。

クライアント側の動作

公開URLを開くと、ログイン不要のフォーム（Email / Display name / Message）が表示される
送信するとゲストアカウントが自動作成される。GitHubアカウントは不要
テンプレートの名前パターンに従ってprojectが作られ、クライアントはCollaboratorとして参加する。Default membersがAdmin、Default agentsがCollaboratorとして同時に参加する
入力したMessageがクライアントの発言としてprojectに投稿され、project画面が開く

ゲストアカウントの制約

ログイン状態は送信したブラウザに保存され、7日間有効
ゲストにはパスワードも再ログイン手段もない。別の端末・別のブラウザから、または7日を過ぎてから、クライアント自身が同じprojectに戻ることはできない
同じクライアントがフォームを再送信すると、メールアドレスが同じでも別の新しいゲストアカウントと新しいprojectが作られる
7日を超える継続案件では、クライアントにGitHubアカウントを用意してもらい、project参加リンクで参加し直す運用が確実である

クライアントが「リンクを開けない」場合は、まずリンクのEnabled、期限、Rotateの有無、テンプレートの有効性を確認する。

接続とクライアント受付を使う前に確認する

aachat initの後、ローカルruntimeを動かした状態でaachat statusを実行します。接続teamとmirrorのhealthyを確認し、意図したProjectをWebUIで開いて秘密情報のないShared Documentを照合します。接続成功はすべてのProjectへのmembership付与や、停止中mirrorの最新性を意味しません。ファイルが古い場合は編集前にmirror状態と現在のアクセス権を解決します。

Registryの索引はaachat/teams/<team>/concepts/_index.yamlとaachat/teams/<team>/entities/_index.yamlの2つです。具体的な編集例はConcept Registryを使います。投影YAMLの保存は変更のstageで、その後check・plan・submitが必要です。Meetingは読み取り専用snapshotで、3つ目の編集可能なRegistryではありません。

client-entry URLを配布する前に、別のブラウザprofileと秘密情報のないテスト入力で、フォーム、作成されたProject、最初のmessage、想定メンバーを確認します。このテストでは実際にguestとProjectが作られます。同じブラウザからProjectを再び開けることを確認し、別端末からも同じように戻れるとは案内しません。長期のクライアントはguest loginの期限前にGitHubアカウントを用意し、意図した既存Projectの参加リンクから参加します。

公開URLが開けない場合は、まずEnabled、期限、templateの有効性、URLのRotateを確認し、通信や表示エラーも調べます。linkやtemplateの無効化は新規受付を止め、作成済みProjectは残します。Rotateは旧フォームURLを無効にしますが、期限切れguest loginは復旧しません。既存会話の復旧としてフォームを再送信しないでください。別guestと別Projectが作られます。templateの3つの意味はTemplatesで比較しています。

外部coding agentの最新の操作入口は、生成されたskillが参照するorchestration-skill.mdです。公開ガイドは利用の流れを説明します。古いcommand一覧を新たなlocal guidanceへコピーせず、生成された接続案内を維持してください。