Stitch SDK Pipeline

This skill orchestrates the full SDK generation pipeline — from capturing MCP tool schemas to publishing a tested, validated package. Use this when:

The Stitch MCP server adds or changes tools
You need to regenerate the SDK from scratch
You want to verify the pipeline is healthy

[!IMPORTANT] Stage 2 is the only step requiring agent intelligence. All other stages are deterministic scripts. For Stage 2, use the stitch-sdk-domain-design skill.

Prerequisites

STITCH_API_KEY environment variable set
bun installed
Working directory: project root (stitch-sdk/)

Pipeline Stages

Stage 1: Capture Tool Schemas 🤖

// turbo
npm run capture

Connects to the Stitch MCP server, calls tools/list, and writes the raw schemas to packages/sdk/generated/tools-manifest.json. Updates the manifest section of stitch-sdk.lock.

Output: packages/sdk/generated/tools-manifest.json (includes inputSchema + outputSchema for every tool)

When to skip: If tools-manifest.json is already up to date and no server-side changes occurred.

Stage 2: Domain Design 🧠 (Agent)

Use the stitch-sdk-domain-design skill for this stage.

Read tools-manifest.json and edit packages/sdk/generated/domain-map.json to map tools → classes → methods.

Key decisions at this stage:

Which class owns each tool?
What are the arg routing rules (self, param, computed, selfArray)?
What is the response projection path?
Should the method cache data from the construction response?

Input: tools-manifest.json + scripts/ir-schema.ts (the canonical IR contract) Output: packages/sdk/generated/domain-map.json

When to skip: If domain-map.json already has the correct bindings and you only changed ir-schema.ts or generate-sdk.ts.

Stage 3: Generate TypeScript 🤖

// turbo
npm run generate

Validates the IR (Zod schema) and every projection (against outputSchema), then emits TypeScript files via ts-morph into packages/sdk/generated/src/.

Output: packages/sdk/generated/src/*.ts + updated stitch-sdk.lock

If this fails with a projection error, go back to Stage 2 and fix domain-map.json.

Stage 4: Build 🤖

// turbo
npm run build

TypeScript compilation: packages/sdk/ → packages/sdk/dist/.

Stage 5: Unit Tests 🤖

// turbo
npm run test

Runs core unit tests (vitest) — mocked callTool, verifying generated method signatures, caching, and error handling.

Stage 6: Script Tests 🤖

// turbo
npm run test:scripts

Runs contract tests (IR schema acceptance/rejection) and logic tests (expression builders) using bun:test.

Stage 7: E2E Tests 🤖

npm run test:e2e

Live API tests against the built package. Requires STITCH_API_KEY (and GEMINI_API_KEY for AI SDK tests). Two test suites:

live.test.ts — Direct SDK calls: create projects, generate screens, verify responses.
ai-sdk-e2e.test.ts — AI SDK integration via stitchTools(): Gemini autonomously calls Stitch tools, generates designs, extracts HTML + Tailwind config, produces modular React components, validates via SWC, and scaffolds a Vite preview app at .stitch/preview/.

Stage 8: Lock Validation 🤖

// turbo
npm run validate:generated

Verifies that stitch-sdk.lock hashes match the actual generated files. Catches drift (someone edited generated files manually or forgot to regenerate).

[!IMPORTANT] Always run after Stage 3 (Generate). If you run Capture (Stage 1) then Validate without re-generating, the hashes will mismatch because the manifest hash changed.

Stage 9: Skill Audit 🧠 (Agent)

After the pipeline passes, audit agent skills for freshness. Read the current source of truth and update any skills that reference stale methods, args, or examples.

Inputs:

packages/sdk/src/index.ts (public surface)
Generated class files in packages/sdk/generated/src/
packages/sdk/src/spec/errors.ts (error codes)
packages/sdk/src/spec/client.ts (config schema)

Skills to audit (in priority order):

stitch-sdk-usage — highest churn, references specific methods and constructor signatures
stitch-sdk-readme — must document stitchTools(), toolDefinitions, and AI SDK integration examples
stitch-sdk-development — check cache examples match current domain-map patterns
stitch-sdk-domain-design — check code examples in the cache section

Skills to skip: stitch-sdk-pipeline (self-referential), red-green-yellow (generic methodology).

What to check:

Every method name in a code example exists on its class
Every import in an example matches an export in index.ts
Constructor signatures match the actual constructors
Config fields match StitchConfigSchema
Error codes match StitchErrorCode

When to skip: If only infrastructure code changed (packages/sdk/src/client.ts, packages/sdk/src/proxy/) and no public API surface changed.

Quick Reference

Full pipeline (script stages only)

npm run pipeline

Runs Stage 1 → 3 → 4 → 5 in sequence. Does not include Stage 2 (agent), Stage 7 (e2e), or Stage 9 (skill audit).

Starting from a specific stage

Scenario	Start from
New tool added to MCP server	Stage 1
Need to change how a tool maps to a method	Stage 2
Changed `ir-schema.ts` or `generate-sdk.ts`	Stage 3
Changed code in `packages/sdk/src/` (client, errors)	Stage 4
Just want to verify everything works	Stage 5
Changed AI SDK tools adapter or tool definitions	Stage 5
Public API surface changed	Stage 9

Key files

File	Location	Role
`tools-manifest.json`	`packages/sdk/generated/`	Raw MCP tool schemas (Stage 1 output)
`domain-map.json`	`packages/sdk/generated/`	IR: tool → class → method mappings (Stage 2 output)
`tool-definitions.ts`	`packages/sdk/generated/src/`	Generated JSON Schema tool definitions for AI SDK
`tools-adapter.ts`	`packages/sdk/src/`	`stitchTools()` — AI SDK v6 adapter (imported via `@google/stitch-sdk/ai`)
`ir-schema.ts`	`scripts/`	Zod schema defining valid IR structure
`tool-schema.ts`	`scripts/`	TypeScript types for JSON Schema
`generate-sdk.ts`	`scripts/`	ts-morph codegen (Stage 3)
`stitch-sdk.lock`	`packages/sdk/generated/`	Integrity hashes for drift detection
`stitch-html.ts`	`packages/sdk/test/helpers/`	Stitch HTML parser (Tailwind config + font extraction)
`component-validator.ts`	`packages/sdk/test/helpers/`	SWC AST validator for generated React components