Telepathy Collaboration

cctelepathy を使用した Claude Code インスタンス間の協調作業ガイド。

チーム協調フロー（JSON定義）

{
  "version": "2.0",

  "prerequisites": {
    "mcp_connection": {
      "required": true,
      "check": "telepathy_list must succeed",
      "on_failure": "スキルフロー開始不可。MCP接続を確認"
    }
  },

  "roles": {
    "leader": {
      "description": "ユーザーとの窓口。チーム調整役",
      "can_talk_to_user": true
    },
    "member": {
      "description": "リーダー指示で作業。テレパシー経由で報告",
      "can_talk_to_user": false,
      "exceptions": ["escalation", "leader_mia"]
    }
  },

  "states": {
    "before_work": {
      "description": "作業開始前",
      "leader_priority": "user_input",
      "member_priority": "telepathy_wait"
    },
    "during_work": {
      "description": "作業中",
      "leader_priority": "telepathy_wait",
      "member_priority": "telepathy_wait"
    },
    "after_work": {
      "description": "全員完了後",
      "leader_priority": "user_input",
      "member_priority": "user_input",
      "trigger": "all_claudes_completed"
    }
  },

  "startup_flow": {
    "step_1": {
      "action": "telepathy_list",
      "purpose": "MCP接続確認 + チーム状況確認",
      "on_failure": "スキル終了。MCP未接続"
    },
    "step_2": {
      "condition": "no_leader_identified",
      "action": "AskUserQuestion",
      "question": {
        "header": "リーダー",
        "question": "このセッションのリーダーは誰ですか？",
        "options": [
          {"label": "自分", "description": "このClaudeがリーダーとして調整役を担う"},
          {"label": "他のClaude", "description": "既にリーダーがいる。メンバーとして待機"},
          {"label": "単独作業", "description": "チーム協調なし。通常モード"}
        ]
      }
    },
    "step_3_leader": {
      "condition": "role == leader",
      "action": "await_user_input",
      "state": "before_work"
    },
    "step_3_member": {
      "condition": "role == member",
      "action": "telepathy_wait_loop"
    }
  },

  "member_wait_loop": {
    "timeout_seconds": 60,
    "note": "Droid has ~60s MCP timeout limit; use shorter timeout with retry loop",
    "retry_pattern": {
      "max_retries": 60,
      "effective_wait_minutes": 60,
      "description": "60回 × 60秒 = 最大60分の待機を短いタイムアウトで実現",
      "reset_total_wait_on_message": false
    },
    "on_message": "process_and_continue (total_wait does NOT reset)",
    "on_timeout": {
      "action": "increment timeout_count and total_wait, then continue loop",
      "leader_check": {
        "condition": "timeout_count % 3 == 0",
        "action": "telepathy_send",
        "content": "see escalation_messages.leader_timeout"
      },
      "user_escalation": "see escalation.user_escalation for condition and action"
    },
    "exit_conditions": [
      "END message with 'user_control'",
      "state == after_work",
      "timeout_count >= member_wait_loop.retry_pattern.max_retries (60回、60分)",
      "total_wait >= member_wait_loop.retry_pattern.effective_wait_minutes * 60 (60分)"
    ]
  },

  "escalation_messages": {
    "leader_timeout": "タイムアウト。リーダー、指示ありますか？"
  },

  "escalation_limits": {
    "max_retries": 60,
    "effective_wait_seconds": 3600
  },

  "escalation": {
    "leader_check": {
      "timeout_count_threshold": 3,
      "description": "3回タイムアウトごとにリーダーへ確認メッセージを送信",
      "message": "see escalation_messages.leader_timeout"
    },
    "user_escalation": {
      "condition": "timeout_count >= escalation_limits.max_retries OR total_wait >= escalation_limits.effective_wait_seconds",
      "action": "AskUserQuestion",
      "message": "最大待機時間に到達しました。指示をお願いします",
      "description": "timeout_count >= escalation_limits.max_retries OR total_wait >= escalation_limits.effective_wait_seconds でユーザーへエスカレーション"
    }
  },

  "leader_failover": {
    "trigger": "leader_disconnected",
    "detection": "telepathy_list でリーダー不在確認",
    "action": "AskUserQuestion で次のリーダー選択"
  },

  "session_recovery": {
    "on_restart": "telepathy_history で最後の状態確認",
    "role_check": "最後のメッセージから役割推測",
    "if_unclear": "AskUserQuestion で役割確認"
  }
}

Quick Start

Option A: /telepathy コマンド（推奨）

/telepathy

コマンドが以下をガイドします：

1. 役割選択（リーダー / メンバー / カスタム）
2. 詳細設定（コンピテンス、性格、振る舞い）
3. telepathy_start の自動呼び出し

Option B: 手動セットアップ

1. MCP接続確認 + 名前・ロール設定

telepathy_list()                              # 接続確認（必須）

# 基本的な参加
telepathy_start({ name: "your-name" })

# ロール付き参加（推奨）
telepathy_start({
  name: "Holmes",
  role: "leader",
  preferredSkills: ["pr-review-toolkit:code-reviewer"],
  profile: {
    competence: ["Architecture", "Code Review"],
    personality: "Methodical and thorough"
  }
})

重要: telepathy_list が失敗する場合、MCP未接続。このスキルは使用不可。

2. 役割確認

リーダーが不明な場合、AskUserQuestion でユーザーに確認:

• 自分がリーダー → ユーザー入力待ち
• 他がリーダー → telepathy_wait() ループ開始
• 単独作業 → 通常モード（チーム協調なし）

ロール設定（Issue #11）

概要

チームメンバーにロールとプロファイルを設定し、様々な組み合わせを探求できます。

ロール定義

ロール	説明	詳細
leader	チーム統括、タスク管理	leader.md
member	タスク実行、報告	member.md
custom	自由設定	-

プロファイル構造

{
  name: string;           // 名前
  role: string;           // "leader" | "member" | カスタム
  preferredSkills: [];    // 使用すべきスキル
  profile: {
    competence: [];       // 何を成し遂げられるか
    personality: string;  // 性格
    strengths: [];        // 強み
    behavior: {
      style: string;      // proactive | reactive
      communication: string;
      focus: string;
    }
  }
}

コンピテンス → スキルマッピング

Claude がコンピテンスを見て、推奨スキルを判断します：

コンピテンス	→ preferredSkills
TypeScript実装, テスト作成	pr-review-toolkit:code-reviewer
UI/UXデザイン	frontend-design:frontend-design
品質レビュー, セキュリティ	pr-review-toolkit:silent-failure-hunter

セッション復帰時のコンテキスト注入

コンパクト後、Hook経由でロール情報が注入されます：

## Your Telepathy Session
- Name: Holmes
- Role: leader
- Competence: Architecture, Code Review
- Preferred skills: pr-review-toolkit:code-reviewer

Remember to embody your character.

役割別の動作

リーダー

状態	優先	動作
作業前	ユーザー入力	タスク受付、チームへ指示出し
作業中	テレパシー	メンバー報告確認、調整
作業後	ユーザー入力	結果報告、次の指示待ち

リーダーの責務:

• タスクの分解・割り当て
• 進捗確認・状況把握
• 技術的アドバイスの提供
• ブロッカーの解消支援
• 最終確認・マージ判断

やってはいけないこと:

• 委任したタスクを自分で実装する ← 重要
• メンバーの作業を待たずに先回り
• 確認なしでメンバーの成果物を上書き

メンバー

状態	優先	動作
作業前	テレパシー待機	リーダー指示待ち
作業中	テレパシー待機	作業 → 報告 → 待機
作業後	ユーザー入力	全員完了後のみ

メンバーの原則:

• 起動後は即 telepathy_wait() でリーダー指示待ち
• テレパシー待機 > ユーザー入力待ち（優先度）
• ユーザーへの直接質問は原則禁止 → リーダー経由で確認

待機ループ

メンバーの待機パターン

注意: Droid には約60秒の MCP タイムアウト制限があります。長時間の待機を実現するには、短いタイムアウトでリトライループを使用します。

timeout_count = 0
total_wait = 0  // 総待機時間（秒）
max_retries = 60  // 60回 × 60秒 = 最大60分
max_wait_minutes = 60  // escalation.max_wait_minutes

while (作業中 && timeout_count < max_retries && total_wait < max_wait_minutes * 60) {
  telepathy_wait(timeout: 60)  // Droid MCP制限に対応した60秒待機

  if (message_received) {
    process_message()
    timeout_count = 0  // timeout_countのみリセット（total_waitはリセットしない）
    continue
  }

  if (timeout) {
    timeout_count++
    total_wait += 60  // 総待機時間更新（60秒タイムアウト × 1回）

    // Leader check: 3回タイムアウトごとに確認
    if (timeout_count % 3 == 0) {
      telepathy_send("タイムアウト。リーダー、指示ありますか？")
    }

    // User escalation: max_retries到達 OR 総待機時間超過
    if (timeout_count >= max_retries || total_wait >= max_wait_minutes * 60) {
      AskUserQuestion("最大待機時間に到達しました。指示をお願いします")
      break
    }
    continue
  }
}

待機ループ終了条件

• END メッセージで「ユーザー制御: 復帰OK」を受信
• 状態が after_work に遷移（全員完了）
• エスカレーション後、ユーザーが終了指示

エスカレーション

メンバーがユーザーに話せる例外

1. タイムアウト60回 or 60分経過 でリーダー無応答（注: 3回ごとにリーダーチェックメッセージ送信）
2. 致命的エラー でリーダーも対応不可
3. リーダーから明示的に「ユーザーに確認して」と指示

リーダー不在時（Failover）

1. telepathy_list でリーダー不在を検知
2. AskUserQuestion で次のリーダーを選択
   - 自分がリーダーになる
   - 他のClaudeを指名
   - 作業終了

セッション復帰

コンパクト後やセッション再起動時:

1. telepathy_list() で接続確認
2. telepathy_history() で最後の状態確認
3. 自分の役割を推測（最後のメッセージから）
4. 不明な場合 → AskUserQuestion で確認
5. 役割に応じて動作再開

未読メッセージ通知

📬 N unread message(s) が表示されたら、即座に確認:

📬 2 unread message(s) from: Mutta, Hibito
↓
# 状況に応じて選択:
telepathy_read()      # プレビュー確認 + 既読化（推奨）
telepathy_unread()    # プレビュー確認のみ（作業中）
telepathy_history()   # 全文確認したい場合

特にチーム作業中は、未読通知を見逃さないこと。

使い分けの例

• 作業開始時・復帰時: telepathy_read() で未読を確認して既読化
• 作業中: telepathy_unread() でチラ見、重要なら後で詳細確認
• 詳細確認: telepathy_history() で全文表示、検索・フィルタ利用

基本ツール一覧

ツール	用途	どういう時に便利か
telepathy_start	名前設定 + 参加通知 + コンテキスト取得	チーム作業開始時。参加を宣言し、最近のコンテキストを取得
telepathy_list	接続中インスタンス一覧（MCP接続確認）	誰がオンラインか確認。MCP接続確認にも使用
telepathy_send	全員にブロードキャスト	チーム全体への通知・報告・質問
telepathy_send_to	特定相手へ DM	特定のメンバーへの個別指示・質問
telepathy_history	メッセージ履歴取得（検索・フィルタ可）	過去の会話確認、特定メッセージ検索、詳細確認
telepathy_wait	メッセージ待機（イベント駆動、推奨）	リアルタイムでメッセージを待つ。メンバーの待機ループに最適
telepathy_read	未読プレビュー + 既読化	朝のキャッチアップ、未読を確認して既読にする
telepathy_unread	未読プレビューのみ（既読化しない）	作業中断せずにチラ見、後で詳細確認予定のメッセージ
telepathy_ack	既読マーク更新（本文表示なし）	ブロードキャスト一括既読、重要DM以外を既読化（target: broadcast/dm/all）
telepathy_project_init	プロジェクト初期化	ブランチ作成後、プロジェクトコンテキストを設定
telepathy_project_update	プロジェクト状態更新	PR番号追加、ステータス変更
telepathy_project_status	プロジェクト状態取得	決定履歴、ブロッカー、マイルストーン確認

プロジェクトステータス追跡（Issue #128）

チームで共有するプロジェクトコンテキストを管理する機能。

ワークフロー

1. telepathy_start          → ネットワーク参加
2. git checkout -b branch   → ブランチ作成
3. telepathy_project_init   → プロジェクト初期化（branch必須）
4. 作業中に myStatus/teamUpdate を送信
5. telepathy_project_status → コンパクト復帰時にコンテキスト確認

myStatus（個人ステータス）

telepathy_send の myStatus パラメータで個人の状態を共有：

myStatus: {
  current: "スキーマ拡張実装中",  // 現在のタスク
  assignment: "Phase 1",          // 割り当て
  stuck: ["型定義が複雑"],        // 個人的な課題
  nextTask: "typecheck 実行"      // 次のタスク
}

teamUpdate（チーム共有情報）

telepathy_send の teamUpdate パラメータでチーム全体に影響する情報を共有：

teamUpdate: {
  decisions: [{
    what: "zod バージョン",
    value: "4.1.8",
    why: "互換性のため"
  }],
  blockers: ["CodeRabbit レビュー待ち"],
  nextMilestone: "PR マージ"
}

stuck vs blockers の使い分け

状況	フィールド	心理的意味
理解不足、技術的な悩み	myStatus.stuck	「助けてもらえると嬉しい」
外部待ち（PR、レビュー）	teamUpdate.blockers	「外部要因で止まっている」
環境問題	teamUpdate.blockers	「チーム全体に影響」

いつ teamUpdate を送るか

✅ 重要な技術決定をした時 → decisions
✅ ブロッカーが発生/解消した時 → blockers
✅ マイルストーンを達成/更新した時 → nextMilestone

❌ 単なる進捗報告 → myStatus.current を使用
❌ 毎回のメッセージ → 負担が大きい

blockers の上書き動作

blockers は追加ではなく上書き。現在のブロッカー完全リストを送信：

// 最初: テスト失敗のみ
blockers: ["テスト失敗調査中"]

// 解決して新しいブロッカー発生 → 前のは含めない
blockers: ["CodeRabbit レビュー待ち"]

// 解消したら空配列
blockers: []

作業モード

{
  "collaboration_modes": {
    "default": "parallel_coordination",

    "parallel_coordination": {
      "description": "テレパシー並列協調（デフォルト）",
      "work": "並列（役割分担）",
      "commit": "順次（コンフリクト回避）",
      "when": "チーム協調作業（gtr不要）",
      "flow": [
        {"step": 1, "action": "リーダーがタスク・役割を割り当て"},
        {"step": 2, "action": "各自が並列作業（編集/レビュー/調査/調整）"},
        {"step": 3, "action": "テレパシーでリアルタイム確認・フィードバック"},
        {"step": 4, "action": "コミットは1人ずつ（コンフリクト回避）"}
      ],
      "roles": [
        "編集担当: コード実装",
        "レビュー担当: コードレビュー（並行可）",
        "調査担当: ドキュメント・コード調査（並行可）",
        "調整担当: ファシリテート（並行可）"
      ],
      "rules": [
        "役割分担で並列作業",
        "コミット前にチームで確認"
      ]
    },

    "parallel_branches": {
      "description": "ブランチ並列（gtr使用時）",
      "work": "並列",
      "commit": "並列（各自ブランチ）",
      "when": "独立したタスクを複数人で同時実装",
      "requires": {
        "gtr_installed": "git gtr --version"
      },
      "setup": {
        "description": "初回セットアップ（必須）",
        "command": "git gtr config set gtr.hook.postCreate \"npm install && npm run typecheck && npm run build\"",
        "note": "hookでworktree作成後に自動実行される。npm以外(yarn/pnpm等)は適宜変更"
      },
      "verification": {
        "check_hook": "git gtr config get gtr.hook.postCreate",
        "expected": "npm install && npm run typecheck && npm run build"
      },
      "flow": [
        {"step": 1, "action": "git gtr new <branch>", "note": "hookが自動でnpm install等を実行"},
        {"step": 2, "action": "cd ../<branch-sanitized>", "note": "worktreeに移動（例: feat/foo → feat-foo）"},
        {"step": 3, "action": "telepathy_send", "content": "着手: #XX 担当: <files>"},
        {"step": 4, "action": "work", "constraint": "担当ファイルのみ編集"},
        {"step": 5, "action": "git push && gh pr create"},
        {"step": 6, "action": "telepathy_send", "content": "完了: #XX PR: <url>"},
        {"step": 7, "action": "git gtr rm <branch>"}
      ],
      "common_mistakes": [
        {"wrong": "git checkout <branch>", "correct": "git gtr new <branch>", "reason": "checkoutはworktreeを作成しない"},
        {"wrong": "元ディレクトリで作業", "correct": "worktreeディレクトリに移動して作業", "reason": "同じディレクトリで複数ブランチ作業は混乱の元"},
        {"wrong": "hook未設定で作業開始", "correct": "setupコマンドで事前設定", "reason": "npm install忘れを防ぐ"}
      ],
      "rules": [
        "worktree作成時にtelepathy_sendで宣言",
        "同じファイルは先に宣言した人が優先",
        "完了時にtelepathy_sendでPR URL共有"
      ],
      "conflict_resolution": {
        "priority": "first_declaration",
        "escalation": "leader_arbitration"
      }
    }
  }
}

gtr クイックリファレンス（parallel_branches用）

コマンド	説明
git gtr list	worktree一覧
git gtr new <branch>	worktree作成
git gtr ai <branch>	Claude起動（初期設定済み時）
git gtr rm <branch>	worktree削除

参照ドキュメント

• メッセージプロトコル v1.0
• Hook 設定ガイド
• ベストプラクティス
• gtr公式リポジトリ

実践例

• PR レビュー協業
• 調査分担