rome: Skill for Claude Code

Validate an OAuth integration

Goal end-state proven: a user opens Settings → Connections, clicks Connect , approves on the provider's consent screen, and Rome holds a delegated token it can call the provider's API with. The recipe is provider-agnostic — only the creds and the registered redirect URL change per provider. Slack (PR #1225) is the worked example throughout.

Validate in three escalating layers. Run them in order; each is cheaper to debug than the next. Report honestly which layers actually ran — Layer 2 needs a registered app, creds, and a human at the consent screen, so it is often where the human takes over.

The cross-service round-trip Layer 2 exercises:

dashboard ──▶ core /api/oauth/<provider>/start ──▶ Pantheon /start
  ──▶ provider authorize (real consent) ──▶ Pantheon /oauth/<provider>/callback
  ──▶ exchangeCode + fetchProfile (verified-email gate) ──▶ broker handoff
  ──▶ dashboard /callback ──▶ core /oauth/redeem ──▶ token persisted + token file

Layer 0 — Static + unit (host, fast)

• pnpm typecheck (all workspaces).
• Touched suites: the Pantheon adapter (pnpm --filter rome-pantheon exec vitest run src/lib/oauth), the core provider lists (pnpm --filter @rome/core exec vitest run src/lib/oauth-providers.test.ts), and the connector (pnpm --filter @rome/app-connector exec vitest run) if the token-consumer half exists.
• Update the drift guards the new provider trips: the enabled-provider lists in packages/core/src/lib/oauth-providers.test.ts and the Rome-managed lists in rome_apps/connector/src/web/lib/connections.test.ts. Any test that used the service as a stand-in Composio toolkit must switch to a still-Composio one (e.g. notion).

Layer 1 — Token usage, no OAuth dance (fast confidence in the consumer code)

Mint a token out-of-band and prove Rome can use it, decoupled from the consent flow:

• In the provider's developer console, "Install to Workspace" (or equivalent) to mint a token without the redirect flow.
• Write it into the rome container by hand at /run/rome/<provider>-oauth-token (single string, or JSON for multi-token services like Slack's {botToken,userToken,teamId}).
• Ask the agent to run connector_proxy against a read endpoint (an auth.test-equivalent) and a write endpoint.