Stitch SDK Domain Design

This skill teaches you how to perform Stage 2 of the generation pipeline: reading tool schemas and producing

domain-map.json

— the intermediate representation that drives codegen.

Your Inputs

tools-manifest.json
— raw MCP tool schemas captured from the server (includes
```
outputSchema
```
)
ir-schema.ts
— Zod schema defining valid domain-map structure (the canonical contract)
Existing
domain-map.json
— the current IR (if extending, not starting fresh)
The
stitch-sdk-development
skill — for understanding the pipeline context

Your Output

A valid

domain-map.json

with two sections:

classes

and

bindings

, validated by

ir-schema.ts

[!IMPORTANT] Your output is validated twice by the codegen: structurally (Zod IR schema) and semantically (projection steps verified against
outputSchema
from the tools-manifest).

Designing Classes

Each class represents a domain entity. Ask: "What noun does the user interact with?"

json

{
  "Stitch": {
    "description": "Main entry point. Manages projects.",
    "constructorParams": [],
    "isRoot": true,
    "factories": [
      { "method": "project", "returns": "Project", "description": "Create a Project handle from an ID." }
    ]
  }
}

Key decisions:

Field	Purpose	Example
`constructorParams`	Fields stored on the instance	`["projectId", "screenId"]`
`fieldMapping`	Per-field data source mapping with optional `stripPrefix`	See below
`parentField`	Which param is injected from a parent class	`"projectId"`
`idField`	Which param the `.id` getter aliases	`"screenId"`
`factories`	Local factory methods (no API call)	`[{ "method": "project", "returns": "Project" }]`

Field Mapping

Use

fieldMapping

when a param needs a different source field, prefix stripping, or a fallback:

json

{
  "constructorParams": ["projectId", "screenId"],
  "fieldMapping": {
    "projectId": { "from": "name", "stripPrefix": "projects/" },
    "screenId": { "from": "id", "fallback": { "field": "name", "splitOn": "/screens/" } }
  }
}

stripPrefix
: Removes a resource name prefix from the value
fallback
: If the primary field is missing, splits an alternate field on a delimiter

Designing Bindings

Each binding maps one MCP tool to one class method. Ask: "Who owns this action?"

Arg routing

Type	Meaning	Code generated
`self`	From `this.field`	`projectId: this.projectId`
`param`	From method parameter	`prompt: prompt`
`computed`	Template interpolation	`name: \` projects/${this.projectId}/screens/${screenId}``
`selfArray`	Wrap self field as array	`selectedScreenIds: [this.screenId]`

Optional params use

"optional": true

. Renamed params use

"rename": "newName"

Response Projections

The

returns.projection

array tells codegen how to navigate the API response. Each step is a

ProjectionStep

typescript

{ prop: string; index?: number; each?: boolean; fallback?: string }

Projection	Generated code	Use when
`[]` (empty)	`raw`	Direct return (whole response)
`[{ "prop": "projects" }]`	`raw.projects`	Array inside object
`[{ "prop": "outputComponents", "index": 0 }, { "prop": "design" }, { "prop": "screens", "index": 0 }]`	`raw.outputComponents[0].design.screens[0]`	Deeply nested single item
`[{ "prop": "outputComponents", "each": true }, { "prop": "design" }, { "prop": "screens", "each": true }]`	`flatMap` chain	Collect all items across arrays
`[{ "prop": "screenshot" }, { "prop": "downloadUrl" }]`	`raw.screenshot.downloadUrl`	Navigate nested properties

Decision: Use

"index": 0

when extracting a single item. Use

"each": true

when collecting all items (array result). You cannot use both on the same step.

[!TIP] Every
prop
in a projection is validated against the tool's
outputSchema
at codegen time. If you typo a property name, codegen will fail with a diagnostic listing the available properties.

Return class wrapping

When

returns.class

is set, the extracted data is wrapped in a domain class constructor:

json

{ "returns": { "class": "Screen", "projection": [{ "prop": "screens" }], "array": true } }

The codegen automatically spreads

parentField

into the data if the child class declares one.

Cache-aware methods

Add a

cache

field with a structured

projection

to check

this.data

before calling the API:

json

{
  "cache": {
    "projection": [{ "prop": "htmlCode" }, { "prop": "downloadUrl" }],
    "description": "Use cached HTML download URL from generation response if available"
  }
}

When the cached property is a nested object (like

File

with a

downloadUrl

), use multiple projection steps to drill into it.

Generated code:

typescript

if (this.data?.htmlCode?.downloadUrl) return this.data?.htmlCode?.downloadUrl;
// ... else call API

Decision Framework

When mapping a new tool, answer these questions:

Which class? Look at which fields the tool requires. If it needs
```
projectId
```
from
```
self
```
, it belongs on
```
Project
```
or
```
Screen
```
. If it needs nothing from self, it belongs on
```
Stitch
```
.
Which method name? Use the verb from the tool name, simplified.
```
generate_screen_from_text
```
→
```
generate
```
.
```
edit_screens
```
→
```
edit
```
.
Arguments from self or param? If the caller already has the data (because they're calling a method on themselves), use
```
self
```
. If they need to provide it, use
```
param
```
.
How deep is the return? Check the tool's
```
outputSchema
```
in
```
tools-manifest.json
```
. Build the
```
projection
```
array step-by-step to navigate to the useful data.
Should it cache? If the data is available from a previous response (like generation), add a cache field with the projection path.

Validation

After editing

domain-map.json

bash

bun scripts/generate-sdk.ts     # Validates IR + projections, then generates
npx tsc --noEmit                 # Type check
npx vitest run                   # Unit tests
bun scripts/e2e-test.ts          # E2E tests
bun scripts/validate-generated.ts  # Lock integrity

If a projection is invalid, you'll see:

❌ Binding "Project.generate" projection step 2:
   property "screenz" not found in outputSchema.
   Available properties: screens, components, metadata

stitch-sdk-domain-design

NPX Install

Tags

SKILL.md Content

Stitch SDK Domain Design

Your Inputs

Your Output

Designing Classes

Key decisions:

Field Mapping

Designing Bindings

Arg routing

Response Projections

Return class wrapping

Cache-aware methods

Decision Framework

Validation