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 🤖

```bash
// 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 🤖

```bash
// 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 🤖

```bash
// turbo
npm run build
```

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

---

### Stage 5: Unit Tests 🤖

```bash
// turbo
npm run test
```

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

---

### Stage 6: Script Tests 🤖

```bash
// turbo
npm run test:scripts
```

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

---

### Stage 7: E2E Tests 🤖

```bash
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 🤖

```bash
// 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)

```bash
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                           |