rome: Skill for Claude Code

Add an OAuth integration

Goal end-state: a user opens Settings → Connections, clicks Connect , approves on the provider's consent screen, and Rome ends up holding a delegated token it can use to call the provider's API on the user's behalf. This mirrors the existing GitHub and Slack integrations — "Rome-managed" providers brokered by Rome's own Pantheon OAuth, with zero Composio involvement.

Work the five phases in order. Don't skip Phase 1 (scoping) — the answers decide how much of Phases 4–5 you build.

The two reference implementations to read and mirror throughout:

• GitHub — the original Rome-managed provider (single token, has a CLI consumer).
• Slack — the most recent, closest template for a fresh service (two tokens, pure API consumer). PR #1225.

Phase 1 — Scope the integration (convey the goal, lock the decisions)

Two things are fixed for this skill and need no confirmation: the integration is OAuth-only (act on the service via its API — real-time inbound events need a central webhook broker and are out of scope) and Rome-managed (our own Pantheon OAuth, direct API, with no Composio connection — never mix the two). State the goal back to the user in one sentence, then resolve the two gates that actually change the build with the human:

1. How many tokens? Some providers return one access token; some return more, each for different methods. Find out — it drives token storage and the proxy's token selection.
2. Token rotation? Default off. Rotation is often irreversible once enabled and adds refresh machinery; only opt in deliberately.

Capture the answers — they are the spec for everything below.

Phase 2 — Learn the provider's delegation mechanism (read the docs)

Read the provider's OAuth documentation and produce a short "build guide" (a scratch doc is fine). Extract exactly these, because the adapter in Phase 4 needs every one:

• Authorization endpoint + params: scope format (space vs comma), state, redirect_uri, and whether it uses PKCE (many confidential-client flows don't — confirm, don't assume).
• Token exchange: endpoint, request encoding, and the response shape — where the access token is, refresh token, expiry, and any extra tokens the response carries beyond the primary one.
• Connecting account's identity — resolve two things for the consenting human: an opaque, stable subject that keys and dedups the connection (the machine identity), and a human-readable handle so a person can recognize which account is wired up (it's the label in Settings → Connections). The handle can come from an OIDC email / email_verified claim or a provider-specific profile API — find whichever the provider exposes (Google has the OIDC claim; GitHub uses /user/emails; Slack uses users.info). Rome broker invariant: the callback (packages/pantheon/src/app/oauth/[provider]/callback/route.ts) currently requires that handle to be a verified email specifically and rejects the handoff without one, so the adapter must produce {email, emailVerified} by whatever means fits — real claim, provider API, or a justified synthesis (Slack treats any returned email as verified, since it only admits verified members). If the provider exposes no email at all (handle-only services), that's a genuine blocker to raise, not a detail — the fix is a broker change (key on subject alone), not something the adapter can paper over. Trap: if the grant mints a service/bot/app identity distinct from the human who clicked Connect, the "whoami" call on the primary token returns the service identity (no email) — resolve the human instead (read the installing user's id from the token response held in bundle.raw, then call the user-profile endpoint) and use the human for subject too.
• Scopes needed for the capabilities you want, and which are sensitive.
• Quirks: e.g. an API that signals errors in the response body rather than the HTTP status; rate-limit headers; a required https redirect.