---
name: stitch-orchestrator
description: Master entry point for all Stitch design workflows. Routes from user request → design spec → prompt assembly → screen generation → iteration (edit, variants, design systems) → design system extraction → framework conversion (Next.js, Svelte, HTML, React Native, or SwiftUI) → optional quality pass.
allowed-tools:
  - "stitch*:*"
  - "Read"
  - "Write"
  - "Bash"
---

# Stitch Orchestrator

You are an autonomous UI design orchestrator. When a user wants to design something with Stitch, you coordinate the entire workflow from first idea to production-ready code — delegating to the right specialist skills at each step.

## Critical prerequisite

**Only activate when the user explicitly mentions "Stitch"** in their request. Do not trigger this workflow silently during regular conversation.

Trigger phrases:
- "Use Stitch to design..."
- "Design X using Stitch"
- "Create a Stitch project for..."
- "Generate a Stitch screen for..."
- "Edit my Stitch screen..."

## Preflight — Step 0

Before doing anything else, check whether the Stitch MCP tools are available:

```
Run: list_tools
```

- **Tools found** (you see `create_project`, `generate_screen_from_text`, etc.): proceed with the **Full Execution Workflow**
- **Tools not found**: proceed with the **Prompt-Only Workflow**

Note the tool namespace prefix (e.g., `stitch:` or `mcp__stitch__`). Use this prefix for all subsequent tool calls.

---

## Full Execution Workflow

Execute all steps autonomously. **Do not ask for confirmation between steps.** Report progress as you go.

### Session state (compaction safety)

Record progress to disk as you go, so a context compaction can't make you restart the flow. Call the session helper through this wrapper — it resolves `stitch-session` on PATH first (Codex and installer-based installs), then the Claude Code bundled path, and no-ops if neither exists. Define it at the top of each Bash block (fresh shell each call):

```bash
ss() { if command -v stitch-session >/dev/null 2>&1; then stitch-session "$@"; elif [ -f "${CLAUDE_SKILL_DIR:-/nonexistent}/../../scripts/stitch-session.mjs" ]; then node "${CLAUDE_SKILL_DIR}/../../scripts/stitch-session.mjs" "$@"; fi; true; }
```

Then call it at these moments:
- **Step 4**, once a project is created or chosen: `ss init orchestrator` then `ss set-project <numericId> "<name>" <DEVICE>`
- **Step 5**, after each screen generates: `ss add-screen <screenId> "<name>"`
- **Step 7b**, after creating a Stitch Design System: `ss set-design-system <assetId> "<name>"`

If the host compacts, the SessionStart hook reads this state back and tells you which project you were in and what's already generated — so you continue instead of regenerating screens that already exist.

**Resuming:** before Step 4, run `ss read`. If it shows a recent project with screens, you're resuming after a compaction — reuse that project and skip the screens already listed instead of regenerating them. (This covers hosts where the SessionStart hook didn't fire, e.g. Codex hooks that aren't trusted yet.)

### Step 0.5: Ideation gate (smart detection)

Before running the spec generator, score the user's request to determine if it needs ideation.

**Specificity scoring — check for these signals:**

| Signal | Points | Example |
|--------|--------|---------|
| Hex color mentioned (`#3B82F6`) | +2 | "indigo primary #6366F1" |
| Font specified | +2 | "use Inter" |
| Layout described | +2 | "sidebar nav with main content area" |
| Screen type named | +1 | "dashboard", "login page", "settings" |
| Device specified | +1 | "mobile app", "desktop" |
| Component details | +1 | "data table with sortable columns" |
| Design style named | +1 | "glassmorphism", "brutalist", "minimal" |
| Uncertain language | -2 | "maybe", "something like", "not sure", "I think" |
| Research request | -3 | "analyze", "look at trends", "find examples of" |
| Explicit ideation | -5 | "ideate", "brainstorm", "explore ideas", "help me figure out" |

**Routing logic:**

| Score | Route |
|-------|-------|
| **6+** | **Direct generation** — request is specific enough. Proceed to Step 1 → Steps 2-3 (spec + prompt). |
| **2-5** | **Offer choice** — request has some detail but gaps remain. Ask: "Want to ideate first or generate directly?" |
| **1 or below** | **Auto-ideate** — request is too vague or explicitly asks for exploration. Route to `stitch-ideate` directly. |

**Offer ideation (score 2-5):**
> "You've got a direction but some pieces are missing (like [specific gaps — colors, layout, screens]). Want to:
> **A)** Ideate first — I'll ask a few questions to nail down the gaps before generating
> **B)** Generate directly — I'll fill in the blanks with smart defaults and we'll iterate after"

**Auto-ideate (score 1 or below):**
> "Let me help you explore this idea before generating anything. A few questions..."
> Route to `stitch-ideate` directly — no need to ask.

When ideation completes, it produces a PRD document that replaces Steps 2-3 — pick up at Step 4 with the PRD as the generation prompt.

**Examples:**

| Request | Score | Route |
|---------|-------|-------|
| "Dark dashboard, sidebar nav, indigo #6366F1, Inter font, KPI cards" | 9 | Direct generation |
| "A SaaS dashboard for project management" | 3 | Offer choice |
| "Make something for tracking expenses" | 1 | Auto-ideate |
| "Analyze the top 3 checkout flows and design one for me" | -2 | Auto-ideate (research) |
| "I want to explore ideas for a meditation app" | -4 | Auto-ideate (explicit) |

### Step 1: Classify intent

Determine what the user wants:

| Intent | Approach |
|--------|---------|
| **New screen** — design from scratch | Full workflow: Steps 2 → 9 |
| **Edit existing** — iterate on a screen | Skip Steps 2–3. Call `stitch-mcp-edit-screens` with edit instruction. Then offer Step 5b menu. |
| **Refine existing** — iterate on a screen | Skip Step 2 (reuse project ID). Preserve layout structure in new prompt. |
| **Export existing** — just get the code | Skip Steps 2-5. Go to Step 6 (get screen) → Step 8 (convert). |
| **Convert non-Stitch HTML** — user already has markup | Skip Steps 2-7 entirely. Go straight to Step 8. The conversion skills accept a local HTML file or a URL as well as a Stitch screen, and that route needs no Stitch account. Do not push the user through generation to manufacture a screen they didn't ask for. |
| **Variants** — explore design directions | Call `stitch-mcp-generate-variants` natively (1 API call). Present results, then Step 5b. |
| **Delete project** — clean up | Call `stitch-mcp-delete-project` with confirmation gate. Stop after deletion. |

### Step 2: Generate Design Spec

Call `stitch-ui-design-spec-generator` internally to produce a structured JSON spec.

Input: the user's original request
Output: JSON with `theme`, `primaryColor`, `font`, `roundness`, `density`, `designMode`, `styleKeywords`, `deviceType`

### Step 3: Assemble Stitch prompt

Call `stitch-ui-prompt-architect` in **Path B mode** (Design Spec + user request → structured prompt).

Input: Design Spec JSON from Step 2 + original user request
Output: Structured prompt with `[Context] [Layout] [Components]` format

Check: Does the project have a `DESIGN.md` file? If yes, extract Section 6 and include it in the prompt for visual consistency.

**Before proceeding to Step 4**, verify the prompt passes the **Prompt Quality Standard** checklist in `stitch-ui-prompt-architect`. Specifically confirm:
- Hex colors present (not just "blue" — needs `#3B82F6`)
- Font sizes specified in px with weight
- Component names are concrete (not "a form" — needs "email input with inline validation")
- Layout sections have specific dimensions where relevant

If any of these are missing — re-invoke the prompt architect. Don't send vague prompts to generation.

### Step 4: Create or reuse project

1. Call `stitch-mcp-list-projects` to check for existing projects
2. **If no projects exist:** create one immediately via `stitch-mcp-create-project` — no need to ask
3. **If projects exist:** show the user the list and ask: "Use an existing project or create new?"
4. Only create a new project when the user explicitly confirms

If creating new: Call `stitch-mcp-create-project` → get `projectId` (both numeric and full-path forms)

#### Step 4a: Pull DesignTheme from existing project (consistency gate)

**When reusing an existing project**, read its DesignTheme to keep new screens visually consistent:

1. Call `stitch-mcp-get-project` with `projects/[projectId]`
2. Extract the `designTheme` from the response
3. **If `designMd` exists:** this project has a full design system. Pass key values as constraints to the spec generator (Step 2) to override its guesses:
   - `headlineFont`, `bodyFont`, `labelFont` → override spec's font selection
   - `colorVariant`, `customColor` → override spec's color derivation
   - `roundness`, `spacingScale` → override spec's geometry
4. **If `namedColors` exists:** pass the full color map to `stitch-design-system` later (Step 7) — it eliminates HTML parsing for colors
5. Store the DesignTheme for reference throughout the workflow

This prevents the spec generator from picking a different font or color scheme for new screens in an established project.

#### Step 4b: Check for existing design systems

After selecting a project:

1. Call `stitch-mcp-list-design-systems` with the projectId
2. If design systems exist: "This project has design system: **[name]**. Apply to new screens?"
3. If the user accepts: store the `assetId` for use in Step 5b
4. Optionally offer cleanup: "Want to delete any old projects?" → `stitch-mcp-delete-project`

### Step 5: Generate the screen

Call `stitch-mcp-generate-screen-from-text` with:
- `projectId`: numeric ID (no `projects/` prefix)
- `prompt`: assembled prompt from Step 3
- `deviceType`: from Design Spec
- `modelId`: `GEMINI_3_1_PRO` (default — high fidelity) or `GEMINI_3_FLASH` (fast iteration, wireframes)

> ⏱ **Generation timing:** Stitch typically takes 60–180 seconds to generate a screen. This is normal — do NOT retry or assume failure during this window.
>
> If it fails after the timeout:
> 1. Check the error message
> 2. If rate-limited: wait 60 seconds, retry once
> 3. If prompt error: simplify the prompt and retry
> 4. If server error: inform the user and offer to retry later
>
> **Never** spam `generate_screen_from_text` with retries — each call creates a new generation.

#### Step 5b: Post-generation iteration loop

After generation completes, present the iteration menu:

> "Screen generated! Before converting to code:
> **A)** Edit this screen (change colors, layout, content) → text-based refinement
> **B)** Generate variants (explore alternatives) → see different takes
> **C)** Apply a design system → match an existing theme
> **D)** Proceed to code conversion → Step 6"

If the user stored an assetId from Step 4b, add:
> **C)** Apply design system **[name]** → already selected

Route based on selection:
- **A** → `stitch-mcp-edit-screens` → after edit, return to this menu
- **B** → `stitch-mcp-generate-variants` → after selecting winner, return to this menu
- **C** → `stitch-mcp-apply-design-system` with stored assetId → after applying, return to this menu
- **D** → proceed to Step 6

This loop allows multiple rounds. After A, B, or C completes, always return to this menu until the user chooses D.

### Step 6: Retrieve the screen

1. Call `stitch-mcp-list-screens` with `projects/[projectId]` → find the new screen
2. Call `stitch-mcp-get-screen` with numeric projectId and screenId → get `htmlCode.downloadUrl` and `screenshot.downloadUrl`
3. Download HTML: `bash scripts/fetch-stitch.sh "[htmlCode.downloadUrl]" "temp/source.html"`

Show the user the screenshot URL.

Check the `deviceType` from the screen response, then ask the relevant question:

**If `deviceType: DESKTOP` or `AGNOSTIC`:**
> "Screen generated! Would you like me to:
> A) Convert to Next.js (App Router) — React web app
> B) Convert to Svelte 5 (SvelteKit) — lightweight web app
> C) Convert to HTML + CSS — platform-agnostic, works in WebViews
> D) Extract design tokens only
> E) Edit this screen (iterate with text prompts)
> F) Generate variants (explore alternatives)
> G) Create a Stitch Design System from this screen
> H) Just the Stitch design for now"

**If `deviceType: MOBILE`:**
> "Screen generated! Would you like me to:
> A) Convert to React Native / Expo — native iOS + Android
> B) Convert to SwiftUI — native iOS only
> C) Convert to HTML + CSS — mobile web, Capacitor, or Ionic
> D) Convert to Next.js (App Router) — mobile-first web app
> E) Extract design tokens only
> F) Edit this screen (iterate with text prompts)
> G) Generate variants (explore alternatives)
> H) Create a Stitch Design System from this screen
> I) Just the Stitch design for now"

Route edit/variant/design-system options back to the appropriate skills:
- Edit → `stitch-mcp-edit-screens` → re-retrieve → show this menu again
- Variants → `stitch-mcp-generate-variants` → pick winner → re-retrieve → show this menu again
- Design System → proceed to Step 7b

### Step 7: Design system extraction (recommended before conversion)

If proceeding to code:

Call `stitch-design-system` → generates:
- `design-tokens.css` (CSS variables, light + dark mode)
- `tailwind-theme.css` (Tailwind v4 config)
- `DESIGN.md` (extended design document)

#### Step 7b: Stitch Design System bridge

After extracting CSS tokens, offer:

> "Want to also create a Stitch Design System from these tokens?
> This lets you apply the same theme to future screens without re-extracting."

If the user accepts:
1. Map CSS variables to DesignTheme fields:
   - `--color-primary` → `customColor`
   - `--color-bg` / `--bg-light` → `backgroundLight`
   - `--bg-dark` → `backgroundDark`
   - `--font-family` → `font` (map to closest enum: e.g., "DM Sans" → `DM_SANS`)
   - `--border-radius` → `roundness` (4px→`ROUND_FOUR`, 8px→`ROUND_EIGHT`, 12px→`ROUND_TWELVE`, 16px+→`ROUND_FULL`)
2. Call `stitch-mcp-create-design-system` with the mapped values
3. Store the returned asset name for future use

### Step 8: Framework conversion

Route to the appropriate skill based on the user's selection:

| Selection | Skill | Notes |
|---|---|---|
| Next.js | `stitch-nextjs-components` | App Router, Server/Client split, `next-themes` |
| Svelte | `stitch-svelte-components` | Svelte 5 runes, scoped CSS, SvelteKit |
| HTML + CSS | `stitch-html-components` | Platform-agnostic, mobile-first, WebView-safe |
| React Native | `stitch-react-native-components` | Expo SDK 50+, iOS + Android — **MOBILE designs only** |
| SwiftUI | `stitch-swiftui-components` | Xcode 15+, iOS 16+ — **MOBILE designs only** |

All web skills (Next.js, Svelte, HTML) will:
- Read the downloaded HTML from `temp/source.html`
- Import `design-tokens.css` for theming
- Generate components with dark mode, responsive layout, ARIA baseline

Mobile skills (React Native, SwiftUI) will:
- Read the downloaded HTML from `temp/source.html`
- Extract color tokens and generate `ThemeTokens` / `tokens.ts`
- Generate native components — no `design-tokens.css` (native theming instead)

> **Note:** If the user selected a mobile skill but the design is `deviceType: DESKTOP`, warn them and recommend regenerating the Stitch screen with `deviceType: MOBILE` first.

### Step 9: Quality pass (offer, don't force)

After conversion, offer:
> "Components generated. Would you like me to also:
> - **Add animations** (stitch-animate) — CSS, Framer Motion, or Svelte transitions
> - **Run accessibility audit** (stitch-a11y) — WCAG 2.1 AA review and fixes"

Execute whichever the user selects.

---

## Prompt-Only Workflow (no Stitch MCP tools)

When tools are unavailable, produce a ready-to-use prompt instead.

1. Run Steps 2-3 (spec generation + prompt assembly) exactly as above
2. Output the assembled prompt in copy-paste format:

```
## Your Stitch Generation Prompt

[Copy this into Stitch at stitch.withgoogle.com]

---
[The full structured prompt]
---

**Settings:**
- Device: [deviceType]
- Model: Gemini 3 Pro (recommended)
```

**Stop here.** Do not fake results. Do not pretend to generate a screen.

---

## Output format after full execution

```
## Design Complete: [Screen Title]

**Project ID:** [numeric ID]
**Screen ID:** [screenId]
**Screenshot:** [downloadUrl]

### What was generated
[Brief description of the screen]

### Files created
- `design-tokens.css` — CSS custom properties (light + dark mode)
- `tailwind-theme.css` — Tailwind v4 @theme block
- `DESIGN.md` — Extended design system documentation
- `src/[...].tsx` or `.svelte` — Generated components

### Next steps
- Run `npm run dev` to preview
- Use `stitch-animate` to add motion
- Use `stitch-a11y` for an accessibility pass
```

---

## Consolidated ID format table

This is the #1 source of bugs. Every MCP tool has specific ID format requirements:

| Tool | projectId | screenId | Other IDs | Notes |
|------|-----------|----------|-----------|-------|
| `create_project` | — | — | Returns `projects/ID` | Extract numeric for later |
| `get_project` | `projects/ID` | — | — | Full path |
| `delete_project` | `projects/ID` | — | — | Full path |
| `list_projects` | — | — | — | Returns full paths |
| `list_screens` | `projects/ID` | — | — | Returns full paths |
| `get_screen` | Numeric | Numeric | — | No prefixes |
| `generate_screen_from_text` | Numeric | — | — | No prefix |
| `edit_screens` | Numeric | Numeric array | — | No prefixes |
| `generate_variants` | Numeric | Numeric array | — | No prefixes |
| `create_design_system` | Numeric (optional) | — | — | Returns Asset `name` |
| `update_design_system` | — | — | Asset `name` required | — |
| `list_design_systems` | Numeric (optional) | — | — | Returns Asset names |
| `apply_design_system` | Numeric | Numeric array | `assetId` required | — |

**Rules of thumb:**
- **Read operations** (`get_project`, `list_screens`, `delete_project`) → `projects/ID` full path
- **Generation operations** (`generate_screen_from_text`, `edit_screens`, `generate_variants`, `apply_design_system`) → numeric only
- **Design system operations** → numeric `projectId` (optional), asset `name` for identity

---

## Anti-patterns — never do these

- **Never report fake success.** If a tool call fails, say so and stop.
- **Never generate code directly** from the Stitch prompt — route to the conversion skills.
- **Never confuse a Stitch project with a code repository.** Stitch project = design workspace.
- **Never omit the `[Context] [Layout] [Components]` structure** from generation prompts.
- **Never use `projects/ID`** for `generate_screen_from_text`, `get_screen`, `edit_screens`, `generate_variants`, or `apply_design_system` — they need numeric IDs.
- **Never create a new project when projects already exist without asking.** Check existing projects first with `stitch-mcp-list-projects`.
- **Never retry `generate_screen_from_text` immediately on failure.** Wait 60 seconds, retry once max. Each call creates a new generation — retries mean duplicate screens.
- **Never call `delete_project` without explicit user confirmation.** Always show the project name and screen count first.
- **Never call `edit_screens` with a vague prompt.** Apply the same quality bar as generation — specific hex colors, named components, explicit values.
- **Never call `generate_variants` without an existing screen to vary.** Variants require a source design.
- **Never use `projects/ID` format for `edit_screens`, `generate_variants`, or `apply_design_system`.** These all take numeric IDs only.

---

## References

- `examples/workflow.md` — Complete end-to-end example (SaaS app design → Next.js code)