1. Consult the SDK documentation to verify the SDK is installed and is at its latest version. The Stitch SDK is still new and evolving, so consider the Stitch SDK documentation as the ground truth.
2. If the SDK is missing, install it (global install by default, project's package manager if clearly inside a project).
3. Verify the API key env var (as named in the docs) is set. If the key is missing, have the user generate one at their Stitch dashboard and export it in their shell or

   .env

   .
4. Make one minimal SDK call to confirm auth. Diagnose and retry once on failure before involving the user.

• Discover MCP tool names through the agent runtime. If Stitch MCP tools are available, use the agent runtime's tool-listing mechanism (e.g.,

  list_tools

  ) to capture exact tool names. Names may be prefixed (e.g.,

  stitch_create_project

  ,

  mcp__stitch__create_project

  ). Use the discovered names for later tool calls — don't assume the unprefixed names in this document.
• Prefer the SDK's own response data over memory. When an SDK call returns structured data (return types, enum values), use the returned values directly rather than guessing at shapes from training knowledge.
• Fail fast, recover quietly. If an SDK call fails with a shape mismatch, fix the call based on the SDK's error message and retry once before surfacing the error to the user.

"Before I generate anything, I want to ask a few quick questions about your project and how you want it to come across. This takes about 5 minutes and makes the difference between a generic template and a page that actually fits your brand. About 10 questions total."

.stitch/metadata.json

1. Ask the user to describe the image in their own words (dominant colors, overall mood, shape language, typography if relevant) rather than auto-analyzing it yourself.
2. Save the original file to

   .stitch/user-assets/

   with a descriptive filename for later handoff.
3. Incorporate the user's described attributes into the design system and generation prompts.
4. Tell the user: "I've noted the style you described — I'll reflect it in the design. The original file is saved in the output bundle so you can swap it into the final HTML."

<img>

1. Create project: Call

   create_project

   with the project/product name as the title.
2. Build DesignSystem object from the translation table above.
3. Create design system: Call

   create_design_system

   on the project.
4. Update design system: Immediately call

   update_design_system

   . This step is required -- create alone does not render the system.
5. Write DESIGN.md: Create

   .stitch/DESIGN.md

   documenting the design system in semantic language:

   # {Project Name} -- Design System
   ## Brand Feel
   {adj1}, {adj2}, {adj3}
   ## Color Direction
   Primary: {color name} ({hex}) -- {why this fits the brand}
   Mode: {Light/Dark}  Variant: {colorVariant}
   ## Typography
   Headlines: {font name} -- Body: {font name}
   ## Shape
   {Roundness description}

6. Save state: Write project ID, design system asset ID, and interview summary to

   .stitch/metadata.json

   .

1. Select sections based on product type (see Section Taxonomy in

   references/stitch-architecture.md

   ).
2. Craft the generation prompt using the template from

   references/stitch-architecture.md

   .
3. Call

   generate_screen_from_text

   with

   deviceType: DESKTOP

   .
4. Generation takes 1-3 minutes. Do NOT retry if it seems slow.
5. Save the HTML output returned by your Stitch SDK call into

   .stitch/designs/

   using a versioned filename:

   desktop-v1.html

   for the first generation,

   desktop-v2.html

   for the next iteration, and so on. Use the same convention for mobile (

   mobile-v1.html

   ,

   mobile-v2.html

   ). Use the SDK's response-handling pattern to retrieve the output — don't perform arbitrary HTTP fetches.
6. Open the saved HTML file in the user's browser so they can see the design at full fidelity. Use

   open

   (macOS),

   xdg-open

   (Linux), or

   start

   (Windows, via

   cmd /c start

   ). If none work in the current environment, tell the user the file path.
7. Save the screen ID to

   .stitch/metadata.json

   under

   screens.desktop.current

   and append to

   screens.desktop.history

   .

1. Save the updated HTML from the Stitch SDK response and open the local file in the browser.
2. Briefly orient the user: "I've opened the latest version in your browser. Hero section at top with the headline and CTA, then {describe sections}, footer at the bottom."
3. Ask the three feedback questions from

   references/interview-framework.md

   :
   • "What's your gut reaction in the first 5 seconds?"
   • "Does this feel like YOUR product?"
   • "Is there anything that feels wrong, missing, or not quite right?"

references/interview-framework.md

• Always open the updated HTML in the browser after any edit or variant selection.
• Update metadata after every state change. Never discard previous versions.
• After 3 rounds of positive feedback: "This is looking solid. Keep iterating or ship it and refine later?"
• After 5 rounds: "What's the single most important change left?"

1. Identify the latest approved versions in

   .stitch/designs/

   (highest

   desktop-vN.html

   , and

   mobile-vN.html

   if mobile was generated). Copy them into the bundle root, renaming desktop to

   index.html

   and mobile to

   mobile.html

   . Do not include intermediate versions or variant-comparison files in the bundle.
2. Generate

   color-tokens.json

   with primary color, colorMode, colorVariant, fonts, roundness.
3. Copy

   .stitch/DESIGN.md

   .
4. Collect user assets from

   .stitch/user-assets/

   if any exist.
5. Generate

   DEPLOY.md

   using the template in

   references/state-and-pitfalls.md

   .
6. Create the zip:

   zip -r "{project-name}-landing-page.zip" "{project-name}-landing-page/"

7. Tell the user: "Bundle is ready at

   {path}

   . See

   DEPLOY.md

   for the deployment checklist."

• Stitch SDK usage and installation documentation:

  https://stitch-design.ai/docs/sdk/ai-sdk

• DESIGN.md documentation and examples:

  https://stitch-design.ai/docs/design-md/overview

• Session interrupted: Check for

  .stitch/metadata.json

  . Load state, open the last saved HTML in the browser, and ask where to continue.
• Generation fails: Do NOT retry immediately. Use

  get_screen

  or

  list_screens

  to check whether it completed asynchronously. If genuinely failed, try once more with a simplified prompt.
• Rate limiting: Inform the user: "Stitch rate-limited. Retrying in 30 seconds."
• Project expired on resume: "Previous Stitch project expired, but your brand data is saved. Recreating now." Re-run Phase 2 from saved interview data.