/stitch-orchestrator

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):

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 exis