Add Google Calendar integration design
Design for /gcal command following the Gmail pattern: - Subcommands: today, tomorrow, week, next, summary - Hybrid interface (subcommands + natural language) - Tiered delegation (Haiku for fetch, Sonnet for analysis) - Reuses existing OAuth credentials with added Calendar scope 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
OpenCode Test
229
plans/2025-01-02-gcal-design.md
Normal file
229
plans/2025-01-02-gcal-design.md
Normal file
@@ -0,0 +1,229 @@
|
||||
# Google Calendar Integration Design
|
||||
|
||||
**Date:** 2025-01-02
|
||||
**Status:** Approved
|
||||
**Primary Use Case:** Agenda overview
|
||||
|
||||
## Overview
|
||||
|
||||
Build a `/gcal` slash command for Google Calendar access, following the same architectural pattern as `/gmail`:
|
||||
- OAuth credentials (reuse existing `~/.gmail-mcp/`)
|
||||
- Python API wrapper with tiered delegation
|
||||
- Skill file defining usage patterns
|
||||
- Read-only by default
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
User types /gcal
|
||||
│
|
||||
▼
|
||||
Command (gcal.md)
|
||||
│
|
||||
├─→ invokes: skill:gcal
|
||||
│
|
||||
▼
|
||||
Skill determines tier
|
||||
│
|
||||
├─→ Haiku: today, tomorrow, week, next (fetch + format)
|
||||
└─→ Sonnet: summary (fetch + analyze)
|
||||
│
|
||||
▼
|
||||
Python helper (gcal_delegate.py)
|
||||
│
|
||||
├─→ Google Calendar API via OAuth
|
||||
└─→ Returns structured JSON
|
||||
│
|
||||
▼
|
||||
PA formats response for user
|
||||
```
|
||||
|
||||
## Components
|
||||
|
||||
| File | Format | Purpose |
|
||||
|------|--------|---------|
|
||||
| `~/.claude/commands/gcal.md` | Markdown | Slash command definition |
|
||||
| `~/.claude/skills/gcal/SKILL.md` | Markdown | Usage patterns and routing |
|
||||
| `~/.claude/mcp/delegation/gcal_delegate.py` | Python | API wrapper + delegation |
|
||||
| `~/.gmail-mcp/credentials.json` | JSON | OAuth credentials (add Calendar scope) |
|
||||
|
||||
## Command Interface
|
||||
|
||||
### Subcommands
|
||||
|
||||
| Subcommand | Description | Tier |
|
||||
|------------|-------------|------|
|
||||
| `today` | Today's agenda | Haiku |
|
||||
| `tomorrow` | Tomorrow's agenda | Haiku |
|
||||
| `week` | Next 7 days, grouped by day | Haiku |
|
||||
| `next` | Next upcoming event | Haiku |
|
||||
| `summary` | Smart analysis of your week | Sonnet |
|
||||
|
||||
### Routing
|
||||
|
||||
```
|
||||
/gcal → Smart default (today if before 6pm, tomorrow if after)
|
||||
/gcal today → Today's agenda
|
||||
/gcal tomorrow → Tomorrow's agenda
|
||||
/gcal week → Next 7 days, grouped by day
|
||||
/gcal next → Next upcoming event only
|
||||
/gcal summary → Sonnet-powered week analysis
|
||||
/gcal <natural> → PA interprets intent, routes to appropriate subcommand
|
||||
```
|
||||
|
||||
### Hybrid Approach
|
||||
|
||||
1. **Exact subcommand match first:** `today`, `tomorrow`, `week`, `next`, `summary`
|
||||
2. **Natural language fallback:**
|
||||
- "what's on today" → today
|
||||
- "this week" → week
|
||||
- "next meeting" → next
|
||||
- "am I busy tomorrow" → tomorrow
|
||||
- "give me an overview" → summary
|
||||
3. **Ambiguous input:** Ask for clarification
|
||||
|
||||
### Smart Default
|
||||
|
||||
```python
|
||||
from datetime import datetime
|
||||
def default_view():
|
||||
return "today" if datetime.now().hour < 18 else "tomorrow"
|
||||
```
|
||||
|
||||
## Output Format
|
||||
|
||||
### Simple List (today/tomorrow/next)
|
||||
|
||||
```
|
||||
📅 Today — Thursday, Jan 2
|
||||
|
||||
9:00 AM Team standup (30m)
|
||||
📍 Zoom · 👥 5 attendees
|
||||
|
||||
10:30 AM 1:1 with Sarah (45m)
|
||||
📍 Conference Room B
|
||||
|
||||
2:00 PM Project review (1h)
|
||||
📍 Google Meet · 👥 8 attendees
|
||||
📝 Q4 roadmap discussion
|
||||
|
||||
No more events today.
|
||||
```
|
||||
|
||||
### Grouped by Day (week)
|
||||
|
||||
```
|
||||
📅 This Week — Jan 2-8
|
||||
|
||||
━━━ Thursday, Jan 2 ━━━
|
||||
9:00 AM Team standup (30m)
|
||||
2:00 PM Project review (1h)
|
||||
|
||||
━━━ Friday, Jan 3 ━━━
|
||||
11:00 AM Client call (1h)
|
||||
|
||||
━━━ Monday, Jan 6 ━━━
|
||||
(no events)
|
||||
|
||||
...
|
||||
```
|
||||
|
||||
### Context Fields
|
||||
|
||||
- 📍 Location or meeting link
|
||||
- 👥 Attendee count
|
||||
- 📝 Description snippet (first ~50 chars)
|
||||
|
||||
### Smart Summary (Sonnet)
|
||||
|
||||
> "Your week is front-loaded — Thursday and Friday are packed with 6 meetings totaling 5.5 hours. Monday-Wednesday are mostly clear, good for deep work. Heads up: the Client call Friday overlaps with your blocked focus time."
|
||||
|
||||
## Python Helper
|
||||
|
||||
### Structure
|
||||
|
||||
```python
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
Google Calendar Delegation Helper
|
||||
|
||||
Usage:
|
||||
gcal_delegate.py today
|
||||
gcal_delegate.py tomorrow
|
||||
gcal_delegate.py week
|
||||
gcal_delegate.py next
|
||||
gcal_delegate.py summary
|
||||
"""
|
||||
|
||||
SCOPES = ['https://www.googleapis.com/auth/calendar.readonly']
|
||||
CREDENTIALS_PATH = "~/.gmail-mcp/credentials.json"
|
||||
|
||||
# Core functions
|
||||
def get_calendar_service() # OAuth flow, returns Calendar API client
|
||||
def fetch_events(start, end) # Returns list of event dicts
|
||||
def format_event(event) # Extracts: time, title, location, attendees, description
|
||||
def delegate(model, prompt) # Calls Claude CLI for Sonnet-tier tasks
|
||||
|
||||
# Subcommand handlers
|
||||
def cmd_today() # fetch_events for today, format, return JSON
|
||||
def cmd_tomorrow() # fetch_events for tomorrow
|
||||
def cmd_week() # fetch_events for 7 days, group by date
|
||||
def cmd_next() # fetch next single event
|
||||
def cmd_summary() # fetch week, delegate to Sonnet for analysis
|
||||
```
|
||||
|
||||
### Output Format
|
||||
|
||||
```json
|
||||
{
|
||||
"tier": "haiku",
|
||||
"operation": "today",
|
||||
"date": "2025-01-02",
|
||||
"events": [...],
|
||||
"count": 3
|
||||
}
|
||||
```
|
||||
|
||||
## OAuth Setup
|
||||
|
||||
### One-Time Setup
|
||||
|
||||
1. Go to [Google Cloud Console](https://console.cloud.google.com/) → APIs & Services
|
||||
2. Enable "Google Calendar API"
|
||||
3. OAuth consent screen → Add scope: `calendar.readonly`
|
||||
4. Delete local token: `rm ~/.gmail-mcp/token.json`
|
||||
5. Run `/gcal today` — triggers re-auth with new scope
|
||||
|
||||
### Scope Detection
|
||||
|
||||
Helper detects missing scope and prompts:
|
||||
```
|
||||
Calendar scope not authorized. Run:
|
||||
rm ~/.gmail-mcp/token.json
|
||||
Then retry /gcal today to re-authenticate.
|
||||
```
|
||||
|
||||
## Delegation Tiers
|
||||
|
||||
| Tier | Operations | Reason |
|
||||
|------|------------|--------|
|
||||
| Haiku | today, tomorrow, week, next | Fetch + format only |
|
||||
| Sonnet | summary | Requires analysis |
|
||||
| Opus | (reserved) | Strategic planning if needed |
|
||||
|
||||
## Policy
|
||||
|
||||
- Read-only operations only
|
||||
- Show context (attendees, location) by default
|
||||
- Summarize results, don't dump raw data
|
||||
- Start with lowest capable model tier
|
||||
|
||||
## Implementation Checklist
|
||||
|
||||
- [ ] Add Calendar scope to GCP OAuth app
|
||||
- [ ] Create `~/.claude/skills/gcal/SKILL.md`
|
||||
- [ ] Create `~/.claude/commands/gcal.md`
|
||||
- [ ] Create `~/.claude/mcp/delegation/gcal_delegate.py`
|
||||
- [ ] Test OAuth re-authorization
|
||||
- [ ] Test all subcommands
|
||||
- [ ] Test natural language fallback
|
||||
Reference in New Issue
Block a user