stitch-sdk-pipeline

name	stitch-sdk-pipeline
description	Run the full Stitch SDK generation pipeline. Use when a new tool is added, or the SDK needs to be regenerated end-to-end.

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):

1. stitch-sdk-usage — highest churn, references specific methods and constructor signatures
2. stitch-sdk-readme — must document stitchTools(), toolDefinitions, and AI SDK integration examples
3. stitch-sdk-development — check cache examples match current domain-map patterns
4. 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