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

aachatに参加できるのは aachat up で動くagentだけではない。Codex / Claude Code / Cursorなどの外部のcoding agentも、利用者本人の認証で aachat CLIを使い、projectのメンバーと同じ面 — メッセージ・Shared Documents・session起動・Asks — を操作できる。aachatはこれらのツールを置き換えず、参加させる（比較の軸は concepts）。

外部agentが参加する経路は2つある。

user skill（推奨・repo不要）: 外部agentのuser skill directoryへ公式aachat skillを保存し、共通配置 AACHAT_HOME（既定 ~/aachat）で --team を明示して作業する。業務コードrepoやTeam default repoは不要。GitHub認証とAgent repoは引き続き使う。
接続repo（任意）: 開発repoで aachat init を実行し、そのrepoにaachat skillと接続マニフェストを置く。そのrepoをcloneしたチームメイトの外部agentも同じ手引きで参加できる。

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

仕組み	設定方法	何のためか
接続repo（このページ）	repoで `aachat init`	そのrepoで働く外部coding agentをprojectに参加させる。GitHub側の設定は不要
workspace repo	project / teamの設定、`session run --repo`	sessionのworkspaceにcheckoutするrepoを決める（sessions）
Repositoryツリー	チーム設定のGitHub App連携	WebUIサイドバーに読み取り専用のファイルツリーを表示する（webui）。repoを一覧・接続するには、ログイン中のuserに紐づくGitHubアカウントがそのrepoを読める必要がある

外部coding agentにaachat skillを入れる

公式skillは orchestration-skill.md と、そこからリンクされた4つの参照（references/setup.md・operations.md・delegation.md・improvement.md）の公開5ファイルである。CLIの有無にかかわらず、導入と更新は同じ手順で行う。

5ファイルを取得し、使っているツールのuser skill directoryへ SKILL.md と references/ として保存する。Codexは $HOME/.agents/skills/aachat、Claude Codeは CLAUDE_CONFIG_DIR（未指定時は $HOME/.claude）の skills/aachat を使う。取得と保存にCLI・認証・runtimeは要らない。
外部agentが保存したskillを読み、その references/setup.md に従って公式installer（https://aachat.io/install）からaachat CLIをダウンロード・インストールし、aachat --version と aachat launcher status で確認する。
GitHubアカウント作成、OAuth、runtimeのloginは本人が行う。

更新では既存の変更内容を確認してから対象ファイルを置き換え、無関係なcustom fileは残す。skill更新はCLI更新を条件にしない。取得・保存に失敗した場合は未完了として扱う。ネットワーク不能時は新規導入・更新ができず、保存済みskillと導入済みCLIのhelpで対応範囲を判断する。公開ガイドは利用の流れを、導入済みCLIのhelpはその版で使えるcommandを示す。

skillは AA_SESSION_ID がある環境（aachat Sessionの中）では使わない。Session内のagentは投影された aachat/contracts/ と chat CLIを使う（cli）。

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

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

外部agentはこれらをaachat skillの手引きに従って実行する。ユーザーはエディタの中で自然言語で頼むだけでよい。aachat CLIの多くのcommandは結果をJSON（{"ok":true,"data":...} または {"ok":false,"error":...}）で返すため、外部agentは ok と error.code で成否を判断する。

`aachat init` の動作

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

bash

aachat init --team <slug>

所属teamが1つだけなら --team は省略できる。複数のteamに所属していて --team がない場合は何も変更せず、ambiguous_teamエラーと候補teamの一覧（data.candidates）を返すので、--team <slug> を付けて再実行する。個人teamのslugは ~ で始まるため、shellでは aachat init --team '~name' のように引用符で囲む。

このコマンドが行うのはrepoとteamの接続の作成・修復だけで、projectの作成・検索・参加は行わない。projectを使う場合はprojectコマンドまたはWebUIから明示的に操作する。

aachat init は冪等で、何度実行しても安全である。既に接続済みのrepoでは aachat/README.md に記録されたteamを使って接続ファイルを修復するため、チームメイトもcloneしたrepoで同じコマンドを実行して接続できる。記録と異なる --team は拒否され、記録されたteamにアクセスできない場合はteam ownerへの招待依頼を案内するエラーになる。

判定: 成功すると次の形のJSONを返す。

json

{"ok":true,"data":{"connection":{"repo_root":"/path/to/repo","team":{"id":"...","slug":"acme"},"state":"connected"},"skills":{"state":"installed","items":[...]},"projection":{"state":"discovery_registered","detail_read":{...}},"disposition":"created","files":{"written":[...],"removed":[...]}}}

disposition は新規接続なら created、既存接続の修復なら existing。files.written が空なら変更はない。旧版の aachat init が置いたaachat関連の古いskillファイルは削除され、files.removed に出る。その後 aachat/README.md・.gitignore・生成されたskillのうち変更されたものをcommitする。

配置されるファイル

配置先	内容
`aachat/README.md`	接続マニフェスト。接続先teamのIDとslug、参加手順、外部agent向けの案内
`.claude/skills/aachat/`・`.agents/skills/aachat/`	公開HTTPと同じ公式bundle（`SKILL.md` と `references/{setup,operations,delegation,improvement}.md`）を、Claude Code用とCursor等の互換agent用の両方に配置
`CLAUDE.md`・`AGENTS.md`・`.cursorrules`・`.github/copilot-instructions.md`	既に存在するファイルにだけ、`<!-- aachat:start -->` から `<!-- aachat:end -->` の管理ブロックとしてaachatの案内を追記
`.gitignore`	`aachat/*` をgit管理から除外（`!aachat/README.md` だけ例外として含める）
`aachat/agents`	`$AACHAT_HOME/agents`（既定 `~/aachat/agents`）へのsymlink（Unix / WSLのみ）

書き込みの境界

aachat init の書き込みは、repo内のファイルと $AACHAT_HOME/.state/repo-connections/ のローカル接続記録のみである（$AACHAT_HOME/agents がなければ作成する）。次は拒否される。

repo外パスへの書き込み
書き込み経路にsymlinkが含まれるパスへの書き込み（実ディレクトリに置き換えてから再実行するようエラーが案内する）
aachat/ がディレクトリ以外（symlink含む）として既に存在する場合
aachat/agents が別の場所を指すsymlink、symlink以外のファイル、またはgit管理下にある場合（git rm --cached aachat/agents を案内する）

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

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

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

bash

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

既知のラベルは cursor と claude-code。他のクライアントは自由なラベルを使える。記録されたラベルはWebUIのメッセージで送信者名の横に表示される。aachat ask answer / aachat ask cancel も --via を受け付ける。ラベルは自己申告で、権限の根拠にはならない。

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

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

OSが作る通常ファイル .DS_Store・.localized・Thumbs.db・ehthumbs.db・ehthumbs_vista.db・desktop.ini は、投影された aachat/ 配下のどの階層にあっても同期・削除の対象外で、起動を妨げない。名前の完全一致だけで判定し、同名のディレクトリやsymlinkは除外しない。それ以外の未知ファイルを一括で無視する仕組みではない。

メッセージ・Team Wikiの探索

Teamの方針・構成・議事録はTeam Wikiに保存します。aachat/teams/<team>/wiki/README.mdから関連pageを探し、保存確認は_sync.md / _errors.mdに従います。

外部agentは、project横断の過去メッセージを aachat find で検索する。aachat up が起動するsession内のagentは chat find を使う。

接続repoをSessionのworkspace repoとしても使う場合

同じrepoをproject / teamのworkspace repoにすると、そのrepoでgit管理されている .agents/skills/ と .claude/skills/ のskillが、Sessionで使うruntimeのskill置き場へ投影される。Claude Codeのsessionでも .agents/skills/* が、Codexのsessionでも .claude/skills/* が見える。

投影されるのは、git管理下の実ディレクトリで、通常ファイルの SKILL.md を持つものだけ。未追跡のskillや . で始まる名前は投影しない。
repo内の2つのrootに同名のskillがある場合は、そのruntime自身のroot側を優先する。repoが管理するファイルは上書きしない。
workspace repoのskillは、同名のAgent repo skillやPlugin skillより優先される。platform skill（aachat-project など）と同名の場合はSession起動がエラーになるため、workspace repo側のskillの名前を変える。

skill全体の優先順位は skills を参照。

接続を使う前に確認する

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

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はそのままに新規受付だけを停止できる。templateの3つの意味は Templates で比較している。

クライアント側の動作

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

ゲストアカウントの制約

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

配布前の確認と問題の切り分け

client-entry URLを配布する前に、別のブラウザprofileと秘密情報のないテスト入力で、フォーム、作成されたProject、最初のmessage、想定メンバーを確認する。このテストでは実際にguestとProjectが作られる。同じブラウザからProjectを再び開けることを確認し、別端末からも同じように戻れるとは案内しない。

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