paulstraw/g-scheduler

g-scheduler は何をしますか？

すべての参加者が空いており、かつ各自の稼働時間内である会議スロットを見つけます。その後、（依頼があった場合のみ）招待状を作成します。Googleカレンダーへのアクセスと時間計算には、バンドルされた2つのスクリプトを使用します。タイムゾーンや夏時間の計算は自分で行わず、スクリプトの出力を使用してください。

スクリプトはこのスキルのディレクトリ内で python3（Windowsの場合は python または py）を使って実行します。scripts/gcal.py と scripts/slots.py です。Python 3.9以上が必要です。

1. アクセス確認

python3 scripts/gcal.py check を実行します。

• gws が見つからない、またはサインインしていない、もしくはPythonエラーで tzdata が必要と表示された場合は、処理を中断し、ユーザーを SETUP.md の手順に沿って1つずつ誘導します。これなしでは続行できません。
• 成功した場合は続行します。my_working_hours: "not set" でも問題ありません。

2. 入力を収集する

• 参加者: 全員をGoogle Workspaceのメールアドレスに解決します。メールアドレスが不明な名前については、python3 scripts/gcal.py find "Ada Lovelace" "Grace" を実行します。このコマンドは組織のディレクトリを検索します。他のツール（Slackやユーザーのメッセージ）も使用できます。find が失敗した場合（スコープ不足、accessNotConfigured、または管理者がディレクトリ共有を無効にしている場合）、名前の検索は利用できません。その理由を一度伝え、SETUP.mdのトラブルシューティングを参照し、他のツールを使用します。メールアドレスが見つからない、不明、またはユーザーの組織外と思われる場合は、確認を取ります。ユーザーは自動的に参加者に追加されます。ユーザーが参加しないと言った場合のみ --exclude-me を渡します。
• 期間: シンプルにします。「次の2週間」は今日から約18日後までを意味します（より早いスロットが優先されます）。特定の日の場合はその日だけです。日付は YYYY-MM-DD 形式で、終了日を含みます。
• 所要時間: デフォルトは60分です。尋ねずに、そのように仮定したと伝えます。
• 任意参加者: 最初から尋ねません。全員を必須参加者として扱います。

3. スロットを見つける

python3 scripts/gcal.py gather [email protected] [email protected] --start 2026-11-10 --end 2026-11-27 \
  | python3 scripts/slots.py

gather のオプション: --duration MIN、--optional EMAIL（繰り返し可能）、--exclude-me、--time-zone TZ（デフォルトはユーザーのカレンダータイムゾーン。このタイムゾーンでスロットのランク付けと表示が行われます）。

出力には slots（最大5つ、1日最大2つ、早い順）、all_required_free、attendees、warnings が含まれます。各スロットには、各参加者のローカル時間とユーザーのタイムゾーンでの時間、missing、missing_optional、at_day_edge（その時間がその日の最初または最後の30分間に該当する参加者）が含まれます。

出力全体を読み取ってください。jq や python -c などでフィルタリングしないでください。warnings が失われます。

特定の時刻を確認する場合（ユーザーが時間を提案した、スロットがリストにない、または後から参加者が追加された場合）、すべての参加者に対して --start と --end を正確にその会議の時刻（RFC3339形式、オフセット付き）に設定して同じパイプラインを実行します。例：--start 2026-11-19T11:00:00-08:00 --end 2026-11-19T12:00:00-08:00。出力の単一スロットに、誰が欠けているかが示されます。自分で空き時間データから空き状況を判断しないでください。

4. 結果を提示する

• ユーザーのタイムゾーンでスロットをリスト表示し、タイムゾーンが異なる場合は各参加者のローカル時間も表示します。
• すべての警告を平易な言葉で繰り返します。稼働時間が仮定された人（タイムゾーンの平日9:00-17:00）と、カレンダーが読み取れなかったために除外された人を名前で挙げます。
• ユーザーが所要時間を指定しなかった場合は、仮定した時間を明示します。
• all_required_free が false の場合、各スロットで誰が欠けているかを伝え、その一部を --optional として再実行するかどうかを尋ねます。誰を任意参加者にするかはユーザーのみが決定します。自分で任意参加者とマークしないでください。
• slots が空の場合はその旨を伝え、範囲を広げるか、会議時間を短くすることを提案します。

5. 招待状を作成する（依頼があった場合のみ）

1. コンテキストからタイトルを起草し、ソースリンク（例：Slackスレッド）があれば短い説明に含めます。

2. ビデオ会議リンクを追加するかどうかを尋ねます。追加する場合は、location と説明文に記載します。Meet や Zoom の会議は作成しません。

3. 正確なイベント（タイトル、ローカル時間、参加者、説明、場所）を表示し、明示的な「はい、送信します」を待ちます。招待メールは全員に送信され、取り消しできません。

4. イベントをCalendar Events リソースとして一時的なJSONファイルに書き込みます。時刻はユーザーのタイムゾーンで指定します。

   {
     "summary": "プロジェクトキックオフ",
     "description": "https://example.slack.com/archives/... からスケジュール",
     "location": "https://zoom.us/j/123",
     "start": {"dateTime": "2026-11-18T10:00:00", "timeZone": "America/Los_Angeles"},
     "end": {"dateTime": "2026-11-18T11:00:00", "timeZone": "America/Los_Angeles"},
     "attendees": [{"email": "[email protected]"}, {"email": "[email protected]"}]
   }
   

5. python3 scripts/gcal.py invite EVENT.json を実行します。このコマンドは常にすべての参加者に招待状を送信します。リクエストを確認したい場合は、先に --dry-run を使用します。

6. 出力から htmlLink をユーザーに伝え、一時ファイルを削除します。

ルール

• invite 以外の操作はすべて読み取り専用です。他のユーザーのカレンダーや稼働時間を決して変更しないでください。
• プレビューしたイベントをユーザーが明示的に確認するまで、招待状を送信しないでください。
• 特定のタイムゾーンの時刻が1時間ずれているように見える場合、マシンのタイムゾーンデータが古い可能性があります（タイムゾーンルールは変更されることがあります。例：2026年のブリティッシュコロンビア州）。SETUP.mdのトラブルシューティングを参照してください。