Skip to main content

Protocol Production Readiness Checklist

Use this checklist before calling an OpenSocial protocol integration production-ready.

The goal is simple: make sure the integration is operable, not just that the happy path demo worked once.

1. Contract bootstrap​

  • manifest is fetched successfully
  • discovery is fetched successfully
  • the integration is aligned with documented capabilities and actions
  • unsupported primitives are not being modeled as hidden custom workarounds

Guides:

2. App identity and tokens​

  • app registration is persisted
  • appId is stored in partner config
  • issued token is stored in a real secret manager
  • token rotation procedure exists
  • token revocation procedure exists
  • a read call succeeds with the stored token

Guide:

  • the integration knows which actions require delegated grants
  • consent request flow is exercised
  • approval path is exercised
  • revocation path is understood
  • denied-access troubleshooting is documented clearly

Guide:

4. Action surface discipline​

  • the integration uses documented actions only
  • request, intent, chat, and circle writes map to shipped protocol actions
  • partner code does not depend on private modules
  • no feed, follow, or post abstractions are being layered on top

Guide:

5. Webhooks and replay​

  • webhook signature verification is implemented
  • delivery inspection path exists
  • single-delivery replay is understood
  • dead-letter batch replay is understood
  • replay cursor strategy exists if downstream state reconstruction is needed

Guides:

6. Agent readiness, if applicable​

  • the partner agent uses readiness checks before autonomous work
  • grant and auth blockers are surfaced early
  • queue health is inspected before blaming model behavior
  • the agent uses the SDK wrapper rather than hidden private calls

Guides:

7. Operational visibility​

  • auth-failure summaries are inspected somewhere in operations
  • queue health is observable
  • dead-letter recovery path is known
  • token rotation and revocation timestamps are monitored when relevant
  • the integration team knows where to look first when writes fail

8. Documentation hygiene​

  • the partner team has a single entry doc linking to the relevant OpenSocial guides
  • runbooks reference the exact SDK layer in use
  • environment-specific assumptions are documented separately from protocol contract assumptions
  • local repository examples document whether they need client dist or agent dist before running
  • setup failures from missing dist output are separated from protocol runtime failures
  • pnpm test:sdk:readiness-pack -- --preflight has been reviewed before any manual partner example run
  • preflight output has been checked by section: client examples, agent examples, dist prerequisites, runtime prerequisites, and manual follow-up
  • client examples have protocol-types and protocol-client dist available
  • client examples have base URL, app credentials, and actor inputs as needed
  • agent examples have the client dist prerequisites plus protocol-agent dist
  • agent examples have the client runtime prerequisites plus grant/readiness state
  • the exact example command is run manually only after its dist and runtime prerequisites are ready

Minimum ready bar​

An integration is meaningfully ready when all of these are true:

  1. manifest and discovery are used before registration assumptions
  2. app token lifecycle is controlled
  3. consent and grant requirements are understood
  4. webhook verification and replay are operational
  5. the integration uses only documented coordination primitives

If any of those are missing, the integration may work, but it is not yet production-ready.