skill: calendar-scheduling

should_trigger:
  - prompt: "Add a 'book a call' page to our site that shows my real availability and creates the Google Calendar event automatically."
    why: Core build — booking surface plus calendar sync (freebusy + events.insert), the skill's whole purpose.
  - prompt: "We keep getting double-booked when two people pick the same slot — fix it."
    why: Non-obvious symptom phrasing; the availability race (browser-computed slots / write-before-recheck) this skill owns.
  - prompt: "Embed Cal.com on the landing page and white-label it so there's no Cal.com branding."
    why: Embed altitude — self-hosted Cal.com embed for full white-label.
  - prompt: "Añade reservas de citas a la web y evita solapamientos con mi calendario de Outlook."
    why: Spanish trigger plus multi-provider sync; routes to the unified-API path, still this skill.
  - prompt: "Build booking inside our own UI with the Cal.com Booker atom and fire a webhook on each booking."
    why: Booker atom altitude plus booking webhook lifecycle — both core to this skill.
  - prompt: "Bookings show the wrong time after the clocks changed last weekend."
    why: Non-obvious DST/timezone-drift symptom; the stored-wall-clock bug this skill prevents.
  - prompt: "Set up minimum notice and a 15-minute buffer so nobody books me back-to-back or in 5 minutes."
    why: Availability rules (buffers + min-notice) computed server-side — part of the core slot flow.

should_not_trigger:
  - prompt: "List and update events on my Google Calendar for an internal dashboard — there's no booking page."
    route_to: google-workspace
    why: Raw calendar CRUD with no booking surface; that is the boundary this skill explicitly disclaims.
  - prompt: "Set up a generic webhook receiver with signature verification and a retry queue for several providers."
    route_to: webhooks
    why: Generic inbound-event infrastructure, not the booking-specific lifecycle.
  - prompt: "When a booking is created, also create a CRM record, post to Slack, and update a Google Sheet."
    route_to: automation-flows
    why: Multi-tool orchestration fan-out, not the act of reserving a slot.
  - prompt: "Charge $50 when someone books a paid appointment."
    route_to: stripe
    why: Payment integration, not scheduling.
  - prompt: "Write and send the booking confirmation email so it doesn't land in spam."
    route_to: email-connector
    why: Email sending/deliverability, not the slot/calendar logic.

capability:
  - scenario: "Design availability + booking for a solo consultant on Google Calendar with a public booking page, preventing double-booking and timezone bugs."
    must_include:
      - "freebusy.query run server-side across the relevant calendars before any slot is offered."
      - "Slots computed server-side applying buffers and minimum notice (not in the browser)."
      - "A narrow OAuth scope (calendar.freebusy / calendar.events.owned / calendar.app.created), not restricted auth/calendar."
      - "Event written with an explicit timeZone (IANA) and the instant stored in UTC."
      - "A booking webhook with signature verification and idempotency on the provider event id."
      - "Reschedule updates the same stored event id and releases the freed slot (no orphaned second event)."
      - "Re-check freebusy inside the write transaction to close the race."

# Evals — calendar-scheduling

`cases.yaml` holds three groups scored by an LLM judge against the rendered
skill — there are no live calendar/API calls. `should_trigger` and
`should_not_trigger` check routing: each prompt is classified and we confirm
this skill owns it, or that it correctly defers to the named sibling (every
`route_to` id is a real skill). `capability` checks that SKILL.md plus
`references/` contain enough to satisfy the `must_include` rubric for a
solo-consultant Google Calendar booking build — freebusy-first slot math, narrow
scopes, timezone-correct writes, a verified idempotent webhook, and orphan-free
reschedule. Run them through the repo's eval runner, which discovers
`evals/cases.yaml` under each skill; there is no standalone harness here. Treat a
judge miss as a signal to sharpen the description's triggers/boundary or fill a
gap in the body, not as noise.

# Google Calendar sync — payloads and edge cases

Facts dated 2026-06-02. Source: developers.google.com/workspace/calendar/api.
For non-booking calendar work (internal dashboards, raw event CRUD), use the
`google-workspace` sibling — this file is the booking-specific subset.

## 1. Availability — `freebusy.query`

POST `https://www.googleapis.com/calendar/v3/freeBusy`. Always query every
calendar that can block time (primary plus secondary calendars).

```json
{
  "timeMin": "2026-06-02T00:00:00Z",
  "timeMax": "2026-06-09T00:00:00Z",
  "timeZone": "Europe/Andorra",
  "items": [{ "id": "primary" }, { "id": "team-room@group.calendar.google.com" }]
}
```

Response returns `calendars.<id>.busy` as an array of `{start, end}` blocks.
Compute open slots = working hours − busy − buffers − minimum-notice window,
**server-side**. The browser renders the result; it never computes it.

## 2. Write — `events.insert` (with a Meet link)

POST `.../calendars/{calendarId}/events?conferenceDataVersion=1`. Set
`timeZone` on both `start` and `end`, or the time drifts to the calendar's
default zone.

```json
{
  "summary": "Intro call",
  "start": { "dateTime": "2026-10-25T10:00:00", "timeZone": "Europe/Andorra" },
  "end":   { "dateTime": "2026-10-25T10:30:00", "timeZone": "Europe/Andorra" },
  "attendees": [{ "email": "invitee@example.com" }],
  "conferenceData": {
    "createRequest": {
      "requestId": "uuid-per-booking",
      "conferenceSolutionKey": { "type": "hangoutsMeet" }
    }
  }
}
```

Persist the returned event `id` — you need it for reschedule and cancel.

## 3. Reschedule / cancel — no orphans

- Reschedule → `events.update` (or PATCH) the **stored event id** with new
  times. Never `events.insert` a second event.
- Cancel → `events.delete` the stored id (or PATCH `status: "cancelled"`), then
  release any slot lock so the old time is offerable again.

## 4. Stay in sync — `watch` + sync tokens, not polling

- **Push channels:** `events.watch` registers a channel that POSTs to your
  callback URL on changes. Channels expire — renew before expiry.
- **Incremental sync:** store the `nextSyncToken` from a list call; pass it as
  `syncToken` next time to fetch only deltas. A `410 Gone` means the token
  expired → do a full resync and capture a fresh token.
- Polling instead is slower, rate-limited, and misses edits between polls.

## 5. Recurring-event edge cases

- A recurring series has one master event; individual occurrences carry a
  `recurringEventId` pointing back to it.
- Editing a single occurrence creates an **exception instance** — update that
  instance's id, not the master, or you mutate the whole series.
- When reading availability, expand instances (`singleEvents=true`) so each
  occurrence's busy block is counted, not just the master.

## 6. Refresh tokens

- The refresh token arrives once (first consent with `access_type=offline`).
  Store it; access tokens are short-lived and you mint new ones from it.
- A `401` on an API call means refresh the access token and retry; a hard
  refresh failure means re-consent (token revoked or scope changed).

# Provider matrix — which scheduling stack wins when

Facts dated 2026-06-02. Pick by what you must *own*, not by brand familiarity.

## Cal.com

- **Hosting:** open-source, cloud or **self-hostable**. Self-host = full
  white-label (point the embed script at your own domain, zero Cal.com brand)
  and **unlimited API access** — no cloud rate limit to design around.
- **REST API:** base `https://api.cal.com/v2`. `POST /v2/bookings` creates
  regular, recurring, and instant bookings with attendee info, metadata, and
  booking-field responses.
- **Booking surfaces:** (a) **embed** — inline / button / modal triggers,
  identical on cloud and self-hosted; (b) **Booker atom** — an open-source
  modular component for a fully custom booking UI inside your app; (c) the v2
  API for headless booking.
- **Webhooks:** `BOOKING_CREATED` / `BOOKING_CANCELLED` / `BOOKING_RESCHEDULED`
  (plus more). Verify the signature; dedupe on the booking id.
- **Wins when:** you want OSS / self-host / white-label, or you need a custom UI
  (atom) without owning calendar sync, or you want no rate-limit anxiety.

## Calendly

- **Auth:** OAuth 2.1 or personal access token. **v1 API and v1 webhooks were
  discontinued in May 2025** — v2 only for new work (REST, JSON).
- **Scheduling API:** the Create Event Invitee endpoint books meetings via API
  with **no redirect / iframe / hosted UI** — headless booking.
- **Single-use scheduling links expire after 90 days** if unused.
- **Webhooks:** `invitee.created`, `invitee.canceled`, and routing-form
  submissions. Scoped `user` or `organization`. **Require a paid plan**
  (Standard / Teams / Enterprise).
- **Wins when:** the org already runs Calendly and you want API booking + events
  without standing up your own scheduler.

## Google Calendar (direct, single provider)

- **Availability:** `freebusy.query` (POST) returns busy blocks per calendar.
- **Write:** `events.insert` (add `conferenceData` to attach a Meet link).
- **Scopes:** `calendar` / `calendar.events` are **restricted** (require a
  third-party security assessment for production). Prefer granular:
  `calendar.app.created`, `calendar.freebusy`, `calendar.events.freebusy`,
  `calendar.events.owned`, `calendar.readonly`.
- **What you own:** OAuth, token refresh, `watch` push channels, incremental
  sync via sync tokens, recurring-event edge cases.
- **Wins when:** one provider, you need direct read/write, and you accept owning
  the integration. Pure CRUD with no booking surface → use `google-workspace`.

## Nylas v3 (unified)

- **Coverage:** Google + Outlook/Exchange + Apple/iCloud behind one API, with
  availability and free/busy endpoints.
- **Caveat:** **domain-scoped** — availability queries are restricted within an
  organization, so **cross-company scheduling needs multiple external calls**.
- **Wins when:** multi-provider but single-org scheduling is fine and you don't
  want to maintain three integrations.

## Cronofy (unified)

- **Coverage:** Google + Outlook/Exchange + Apple/iCloud behind one API.
- **No domain restriction:** a single call can span domains; caches free/busy in
  a Sync Engine.
- **Wins when:** multi-provider AND **cross-domain** scheduling matters (booking
  across companies in one availability call).

## Quick chooser

- Fastest page, no UI work → Cal.com / Calendly **embed**.
- Own UI + own data model → Cal.com **Booker atom** or **Scheduling API**.
- One provider, direct control → **Google direct** (`freebusy.query` + `events.insert`).
- Many providers, single org → **Nylas v3**.
- Many providers, cross-domain → **Cronofy**.

#!/usr/bin/env bash
# verify.sh — calendar-scheduling lint. Run inside YOUR project against the
# generated scheduling integration. Read-only: it greps, it never edits.
#
# Usage:
#   bash scripts/verify.sh [path]      # default path: .
#
# Lints three definite booking hazards (a lint, not a build):
#   1. Over-broad Google scope — restricted auth/calendar or auth/calendar.events
#      requested where a narrower scope (calendar.freebusy, calendar.app.created,
#      calendar.events.owned) would do.
#   2. Timezone hazard — a Google event payload with a dateTime but no timeZone.
#   3. Webhook unsafety — a booking webhook handler with neither a signature
#      verification nor an idempotency key.
#
# Exit non-zero ONLY on a definite hazard. Empty/clean target -> exit 0.
# Prose-only configs (docs, READMEs) pass the scope/timezone checks.
#
# Env: NO_COLOR=1 disables color.
# Portability: stock macOS bash 3.2 and CI bash 5. No mapfile, no bash-4 features.
set -euo pipefail

ROOT="${1:-.}"

if [[ -n "${NO_COLOR:-}" ]]; then YEL=""; GRN=""; RED=""; RST=""
else YEL=$'\033[33m'; GRN=$'\033[32m'; RED=$'\033[31m'; RST=$'\033[0m'; fi
warn() { printf '%s[skip]%s %s\n' "$YEL" "$RST" "$*"; }
ok()   { printf '%s[ ok ]%s %s\n' "$GRN" "$RST" "$*"; }
fail() { printf '%s[fail]%s %s\n' "$RED" "$RST" "$*"; }

if [[ ! -e "$ROOT" ]]; then warn "path not found: $ROOT (nothing to lint)"; exit 0; fi

# Collect candidate source files (NUL-delimited; bash-3.2-safe, no mapfile).
FILES=()
while IFS= read -r -d '' f; do
  FILES+=("$f")
done < <(find "$ROOT" \
  \( -path '*/node_modules/*' -o -path '*/vendor/*' -o -path '*/.git/*' \
     -o -path '*/dist/*' -o -path '*/build/*' \) -prune \
  -o -type f \( -name '*.ts' -o -name '*.tsx' -o -name '*.js' -o -name '*.jsx' \
     -o -name '*.py' -o -name '*.go' -o -name '*.rb' -o -name '*.json' \
     -o -name '*.yaml' -o -name '*.yml' -o -name '*.env*' \) -print0 2>/dev/null)

if [[ ${#FILES[@]} -eq 0 ]]; then
  ok "no scheduling source files under $ROOT — nothing to lint"
  exit 0
fi

FAILED=0

# 1. Over-broad Google scope. The restricted scopes are the full-string forms;
#    do not flag the granular .freebusy/.app.created/.events.owned/.readonly ones.
SCOPE_HITS=""
for f in ${FILES[@]+"${FILES[@]}"}; do
  if grep -Eq 'auth/calendar(\.events)?["'\'' ,)]' "$f" 2>/dev/null \
     || grep -Eq 'auth/calendar(\.events)?$' "$f" 2>/dev/null; then
    # exclude lines that are actually a narrower scope
    if grep -E 'auth/calendar(\.events)?["'\'' ,)$]' "$f" 2>/dev/null \
        | grep -Ev 'freebusy|app\.created|events\.owned|readonly|events\.freebusy' >/dev/null 2>&1; then
      SCOPE_HITS="$SCOPE_HITS $f"
    fi
  fi
done
if [[ -n "$SCOPE_HITS" ]]; then
  fail "restricted Google scope (auth/calendar or auth/calendar.events) found in:$SCOPE_HITS"
  fail "  -> use calendar.freebusy / calendar.app.created / calendar.events.owned to avoid the security assessment"
  FAILED=1
else
  ok "no over-broad Google calendar scopes"
fi

# 2. Timezone hazard — a Google event payload with dateTime but no timeZone in
#    the same file. Heuristic: files mentioning dateTime must also mention timeZone.
TZ_HITS=""
for f in ${FILES[@]+"${FILES[@]}"}; do
  if grep -q 'dateTime' "$f" 2>/dev/null; then
    if ! grep -q 'timeZone' "$f" 2>/dev/null; then
      TZ_HITS="$TZ_HITS $f"
    fi
  fi
done
if [[ -n "$TZ_HITS" ]]; then
  fail "event payload uses dateTime without timeZone (drifts after DST) in:$TZ_HITS"
  fail "  -> set timeZone (IANA id) on start/end; store the instant in UTC"
  FAILED=1
else
  ok "no naive datetime payloads (timeZone present where dateTime is)"
fi

# 3. Webhook unsafety — a booking webhook handler with neither signature
#    verification nor an idempotency key.
WH_HITS=""
for f in ${FILES[@]+"${FILES[@]}"}; do
  if grep -Eiq 'invitee\.(created|canceled)|BOOKING_(CREATED|CANCELLED|RESCHEDULED)|webhook' "$f" 2>/dev/null; then
    has_sig=0; has_idem=0
    grep -Eiq 'signature|verifySignature|constructEvent|x-cal-signature|x-hook-signature|hmac' "$f" 2>/dev/null && has_sig=1
    grep -Eiq 'idempoten|dedupe|event[_.]?id|already[_ ]?processed' "$f" 2>/dev/null && has_idem=1
    if [[ $has_sig -eq 0 && $has_idem -eq 0 ]]; then
      WH_HITS="$WH_HITS $f"
    fi
  fi
done
if [[ -n "$WH_HITS" ]]; then
  fail "booking webhook handler with no signature verification AND no idempotency key in:$WH_HITS"
  fail "  -> verify the provider signature and dedupe on the provider event id"
  FAILED=1
else
  ok "booking webhook handlers verify a signature or dedupe (or none present)"
fi

echo
if [[ $FAILED -ne 0 ]]; then
  fail "calendar-scheduling lint found definite hazards above"
  exit 1
fi
ok "calendar-scheduling lint clean"
exit 0