Skip to content

google-labs-code/stitch-sdk / .agents/skills/stitch-sdk-domain-design

stitch-sdk-domain-design

Verified

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.

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?"

{
  "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:

FieldPurposeExample
constructorParamsFields stored on the instance["projectId", "screenId"]
referenceIdentity-map keys (.id aliases the LAST key){ "keys": ["projectId", "screenId"] }
parentFieldWhich param is injected from a parent class"projectId"
factoriesLocal factory methods (no API call)[{ "method": "project", "returns": "Project" }]
sideEffectsHandwritten extension methods (declared, never generated)[{ "method": "upload", "reason": "private_rest", "specPath": "src/spec/upload.ts" }]
extensionPathModule re-exporting the class with handwritten methods"../../src/project-ext.js"

[!IMPORTANT] The IR schema is STRICT. Unknown keys are hard validation errors, not silently ignored. Per-field source-mapping helpers described in older docs were never implemented and do not exist — identity fields are populated by the EntityManager from reference.keys, resource name parsing, and id fallback. If validation rejects a key you expected to exist, the feature does not exist — do not work around it.


Designing Bindings

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

Arg routing

TypeMeaningCode generated
selfFrom this.fieldprojectId: this.projectId
paramFrom method parameterprompt: prompt
computedtemplate interpolation ("template": "projects/{projectId}")name: \projects/${this.projectId}/screens/${screenId}``
selfArrayWrap self field as arrayselectedScreenIds: [this.screenId]

Optional params use "optional": true. Renamed params use "rename": "newName". A "default": "VALUE" (requires optional: true) is sent when the caller omits the value: deviceType: options?.deviceType ?? "DESKTOP".

[!IMPORTANT] Method signature shape (D12): required params are positional, in IR order; ALL optional params are emitted into a single trailing options?: { ... } object. generate(prompt, options?), never generate(prompt, deviceType?).

Response Projections

The returns.projection array tells codegen how to navigate the API response. Each step is a ProjectionStep:

{ prop: string; index?: number; each?: boolean; find?: string; acknowledgeSingle?: boolean }
ProjectionGenerated codeUse when
[] (empty)rawDirect return (whole response)
[{ "prop": "projects" }]raw.projectsArray 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 chainCollect all items across arrays
[{ "prop": "screenshot" }, { "prop": "downloadUrl" }]raw.screenshot.downloadUrlNavigate 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. "find": "a.b" scans an array for the first element whose nested path is non-null.

[!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. Stepping THROUGH an array without index/each/find is also a codegen error — the emitted chain would be undefined at runtime.

[!WARNING] Truncation lint: using index or find on an UNBOUNDED array emits a warning — every other element is silently dropped (this exact pattern caused project.generate() to return one screen of many). Prefer "each": true + "array": true. Only if the result is semantically singular, acknowledge it with "acknowledgeSingle": true on the step.

Return class wrapping

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

{
  "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:

{
  "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:

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:

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
writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 319kUpdated Claude CodeCodexVerifiedInstall
xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release.Stars: 118kUpdated Claude CodeCodexVerifiedInstall