# Stitch SDK Domain Design

> Stitch SDK Domain Design is an Agent Skill for development published in the google-labs-code/stitch-sdk repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Design the domain model for the Stitch SDK. Use when mapping MCP tools to domain classes and bindings in domain-map.json. This is Stage 2 of the generation pipeline.

- Skill name: `stitch-sdk-domain-design`
- Category: [Development](https://www.openparable.com/skill/development/1)
- Source: https://github.com/google-labs-code/stitch-sdk/blob/HEAD/.agents/skills/stitch-sdk-domain-design/SKILL.md
- Repository: google-labs-code/stitch-sdk (1,748 GitHub stars when collected)

## SKILL.md

# 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

1. **`tools-manifest.json`** — raw MCP tool schemas captured from the server (includes `outputSchema`)
2. **`ir-schema.ts`** — Zod schema defining valid domain-map structure (the canonical contract)
3. **Existing `domain-map.json`** — the current IR (if extending, not starting fresh)
4. **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:

1. **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`.

2. **Which method name?** Use the verb from the tool name, simplified. `generate_screen_from_text` → `generate`. `edit_screens` → `edit`.

3. **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`.

4. **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.

5. **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
```

---

Source: https://www.openparable.com/skill/development/stitch-sdk-domain-design (OpenParable). Cite the canonical URL above.
