Sourced*

Agent playbooks

Agent playbook: migrate from Stainless to Sourced in one pass

· 4 min read · Sourced

  • agents
  • migration
  • stainless
  • openapi
  • sdks

This page is written for a coding agent. If the user says "move us off Stainless," do not start by editing package names. Start by proving what exists, then choose either the manual migration path or the Sourced preview path.

Agent objective

Migrate the developer-experience surface without breaking customer installs:

  • OpenAPI remains the API contract.
  • stainless.yml remains the migration map.
  • TypeScript and Python package names are preserved unless the user asks otherwise.
  • Client package previews, docs preview, logs, and a compatibility report are generated before publishing; standalone skill-file and MCP outputs are reviewed separately when needed.
  • npm, PyPI, GitHub repo sync, and custom-domain writes stay behind explicit approval.

Minimum inventory

Collect these files or facts before changing anything:

  1. Canonical OpenAPI file.
  2. stainless.yml.
  3. Current TypeScript package name, npm scope, repo, and latest version.
  4. Current Python package name, PyPI project, repo, and latest version.
  5. Docs host, docs repo, custom domain, redirects, sitemap, and llms.txt.
  6. Any MCP target, skill files, README examples, and auth environment variables.
  7. CI workflows that publish SDKs or docs.

If stainless.yml is missing, do not use the Stainless migration flow; run local inventory only or use the normal OpenAPI preview after approval, and mark Stainless parity as blocked. If any other inventory item is missing, say what is missing and continue with read-only local review until the user approves any upload.

Manual path

Use this path when the team does not want a Sourced account:

  1. Validate OpenAPI and fix parse errors.
  2. Read stainless.yml and map resources to OpenAPI operationId values.
  3. Generate SDKs with the team's chosen generator.
  4. Diff old and new public method surfaces.
  5. Build docs from OpenAPI, then create llms.txt, redirects, and sitemap.
  6. Generate or hand-write MCP tools from OpenAPI operations.
  7. Write a skill file that explains auth, safe operations, destructive operations, rate limits, and examples.
  8. Run package smoke tests.
  9. Only then prepare a review report for npm, PyPI, GitHub, and docs-domain writes.

The manual path is fine, but it is many moving parts. Keep a migration report in the repo.

Sourced path

Use this path when the team wants free previews before deciding:

  1. Open Sourced agent onboarding.
  2. After user approval, upload OpenAPI and stainless.yml in the migration flow. If stainless.yml is missing, do not use the Stainless migration flow; use the normal OpenAPI preview after approval and mark Stainless parity as blocked.
  3. Review the generated TypeScript and Python client packages.
  4. Review the docs preview, llms.txt, sitemap, examples, and redirect plan.
  5. Use the standalone skill-file and MCP generator tools if agent artifacts are needed.
  6. Read the compatibility report for missing methods, package metadata, auth drift, and docs drift.
  7. Leave writes disabled until a human approves the exact repo and branch, npm package and version, PyPI project and version, docs domain, DNS records, and indexability change.

Free previews are enough for migration planning. Paid workflows begin when the team wants production continuity: repo sync, registry publishing, production docs hosting, or custom domains.

Prompt to give another agent

You are migrating our API developer experience from Stainless to Sourced.
First inventory OpenAPI, stainless.yml, SDK packages, docs host, MCP, skill files, and publish settings.
Do not publish to npm, PyPI, GitHub, or docs DNS.
Produce a migration report with: preserved package names, generated artifacts, compatibility gaps, docs redirects, skill-file notes, MCP tool list, and approval gates.
Ask before creating or signing into a Sourced workspace or uploading OpenAPI, stainless.yml, SDK source, docs source, or package metadata to any third-party service.
Use Sourced free preview after approval if available; otherwise do the manual path and explain the tradeoffs.

Stop conditions

Stop and ask the user before:

  • Publishing a package.
  • Changing docs DNS.
  • Merging generated SDK output into a production repo.
  • Removing old Stainless docs or packages.
  • Replacing package names.
  • Sending API keys, tokens, or credentials into a third-party service.
  • Creating or signing into a Sourced workspace.
  • Uploading OpenAPI, stainless.yml, SDK source, docs source, or package metadata to any third-party service.
  • Missing methods, auth or environment-variable drift, package-name drift, unsupported required SDK language, docs redirect gaps, failed smoke tests, or unclear owner approval.

Sourced-specific acceptance

The migration is ready for human review when Sourced has produced client package previews, docs preview, logs, and a written compatibility report, and any standalone skill/MCP outputs needed for launch have been reviewed separately. The migration is not ready for production until release readiness says GitHub, npm, PyPI, docs hosting, and custom domain are each approved.