stitch-loop

Stitch Build Loop

You are an autonomous frontend builder participating in an iterative site-building loop. Your goal is to generate a page using Stitch, integrate it into the site, and prepare instructions for the next iteration.

When to Use

• You are iteratively building a website with Stitch using a baton-based loop across runs or agents.
• Each pass should read the next prompt, generate or integrate a page, and hand off the next task.
• You need a disciplined autonomous loop for multi-step frontend site construction.

Overview

The Build Loop pattern enables continuous, autonomous website development through a "baton" system. Each iteration:

1. Reads the current task from a baton file (.stitch/next-prompt.md)
2. Generates a page using Stitch MCP tools
3. Integrates the page into the site structure
4. Writes the next task to the baton file for the next iteration

Prerequisites

Required:

• Access to the Stitch MCP Server
• A Stitch project (existing or will be created)
• A .stitch/DESIGN.md file (generate one using the design-md skill if needed)
• A .stitch/SITE.md file documenting the site vision and roadmap

Optional:

• Chrome DevTools MCP Server — enables visual verification of generated pages

The Baton System

The .stitch/next-prompt.md file acts as a relay baton between iterations:

---
page: about
---
A page describing how jules.top tracking works.

**DESIGN SYSTEM (REQUIRED):**
[Copy from .stitch/DESIGN.md Section 6]

**Page Structure:**
1. Header with navigation
2. Explanation of tracking methodology
3. Footer with links

Critical rules:

• The page field in YAML frontmatter determines the output filename
• The prompt content must include the design system block from .stitch/DESIGN.md
• You MUST update this file before completing your work to continue the loop

Execution Protocol

Step 1: Read the Baton

Parse .stitch/next-prompt.md to extract:

• Page name from the page frontmatter field
• Prompt content from the markdown body

Step 2: Consult Context Files

Before generating, read these files:

File	Purpose
.stitch/SITE.md	Site vision, Stitch Project ID, existing pages (sitemap), roadmap
.stitch/DESIGN.md	Required visual style for Stitch prompts

Important checks:

• Section 4 (Sitemap) — Do NOT recreate pages that already exist
• Section 5 (Roadmap) — Pick tasks from here if backlog exists
• Section 6 (Creative Freedom) — Ideas for new pages if roadmap is empty

Step 3: Generate with Stitch

Use the Stitch MCP tools to generate the page:

1. Discover namespace: Run list_tools to find the Stitch MCP prefix
2. Get or create project:
   • If .stitch/metadata.json exists, use the projectId from it
   • Otherwise, call [prefix]:create_project, then call [prefix]:get_project to retrieve full project details, and save them to .stitch/metadata.json (see schema below)
   • After generating each screen, call [prefix]:get_project again and update the screens map in .stitch/metadata.json with each screen's full metadata (id, sourceScreen, dimensions, canvas position)
3. Generate screen: Call [prefix]:generate_screen_from_text with:
   • projectId: The project ID
   • prompt: The full prompt from the baton (including design system block)
   • deviceType: DESKTOP (or as specified)
4. Retrieve assets: Before downloading, check if .stitch/designs/{page}.html and .stitch/designs/{page}.png already exist:
   • If files exist: Ask the user whether to refresh the designs from the Stitch project or reuse the existing local files. Only re-download if the user confirms.
   • If files do not exist: Proceed with download:
     • htmlCode.downloadUrl — Download and save as .stitch/designs/{page}.html
     • screenshot.downloadUrl — Append =w{width} to the URL before downloading, where {width} is the width value from the screen metadata (Google CDN serves low-res thumbnails by default). Save as .stitch/designs/{page}.png

Step 4: Integrate into Site

1. Move generated HTML from .stitch/designs/{page}.html to site/public/{page}.html
2. Fix any asset paths to be relative to the public folder
3. Update navigation:
   • Find existing placeholder links (e.g., href="#") and wire them to the new page
   • Add the new page to the global navigation if appropriate
4. Ensure consistent headers/footers across all pages

Step 4.5: Visual Verification (Optional)

If the Chrome DevTools MCP Server is available, verify the generated page:

1. Check availability: Run list_tools to see if chrome* tools are present
2. Start dev server: Use Bash to start a local server (e.g., npx serve site/public)
3. Navigate to page: Call [chrome_prefix]:navigate to open http://localhost:3000/{page}.html
4. Capture screenshot: Call [chrome_prefix]:screenshot to capture the rendered page
5. Visual comparison: Compare against the Stitch screenshot (.stitch/designs/{page}.png) for fidelity
6. Stop server: Terminate the dev server process

Note: This step is optional. If Chrome DevTools MCP is not installed, skip to Step 5.

Step 5: Update Site Documentation

Modify .stitch/SITE.md:

• Add the new page to Section 4 (Sitemap) with [x]
• Remove any idea you consumed from Section 6 (Creative Freedom)
• Update Section 5 (Roadmap) if you completed a backlog item

Step 6: Prepare the Next Baton (Critical)

You MUST update .stitch/next-prompt.md before completing. This keeps the loop alive.

1. Decide the next page:
   • Check .stitch/SITE.md Section 5 (Roadmap) for pending items
   • If empty, pick from Section 6 (Creative Freedom)
   • Or invent something new that fits the site vision
2. Write the baton with proper YAML frontmatter:

---
page: achievements
---
A competitive achievements page showing developer badges and milestones.

**DESIGN SYSTEM (REQUIRED):**
[Copy the entire design system block from .stitch/DESIGN.md]

**Page Structure:**
1. Header with title and navigation
2. Badge grid showing unlocked/locked states
3. Progress bars for milestone tracking

File Structure Reference

project/
├── .stitch/
│   ├── metadata.json   # Stitch project & screen IDs (persist this!)
│   ├── DESIGN.md       # Visual design system (from design-md skill)
│   ├── SITE.md         # Site vision, sitemap, roadmap
│   ├── next-prompt.md  # The baton — current task
│   └── designs/        # Staging area for Stitch output
│       ├── {page}.html
│       └── {page}.png
└── site/public/        # Production pages
    ├── index.html
    └── {page}.html

.stitch/metadata.json Schema

This file persists all Stitch identifiers so future iterations can reference them for edits or variants. Populate it by calling [prefix]:get_project after creating a project or generating screens.

{
  "name": "projects/6139132077804554844",
  "projectId": "6139132077804554844",
  "title": "My App",
  "visibility": "PRIVATE",
  "createTime": "2026-03-04T23:11:25.514932Z",
  "updateTime": "2026-03-04T23:34:40.400007Z",
  "projectType": "PROJECT_DESIGN",
  "origin": "STITCH",
  "deviceType": "MOBILE",
  "designTheme": {
    "colorMode": "DARK",
    "font": "INTER",
    "roundness": "ROUND_EIGHT",
    "customColor": "#40baf7",
    "saturation": 3
  },
  "screens": {
    "index": {
      "id": "d7237c7d78f44befa4f60afb17c818c1",
      "sourceScreen": "projects/6139132077804554844/screens/d7237c7d78f44befa4f60afb17c818c1",
      "x": 0,
      "y": 0,
      "width": 390,
      "height": 1249
    },
    "about": {
      "id": "bf6a3fe5c75348e58cf21fc7a9ddeafb",
      "sourceScreen": "projects/6139132077804554844/screens/bf6a3fe5c75348e58cf21fc7a9ddeafb",
      "x": 549,
      "y": 0,
      "width": 390,
      "height": 1159
    }
  },
  "metadata": {
    "userRole": "OWNER"
  }
}

Field	Description
name	Full resource name (projects/{id})
projectId	Stitch project ID (from create_project or get_project)
title	Human-readable project title
designTheme	Design system tokens: color mode, font, roundness, custom color, saturation
deviceType	Target device: MOBILE, DESKTOP, TABLET
screens	Map of page name → screen object. Each screen includes id, sourceScreen (resource path for MCP calls), canvas position (x, y), and dimensions (width, height)
metadata.userRole	User's role on the project (OWNER, EDITOR, VIEWER)

Orchestration Options

The loop can be driven by different orchestration layers:

Method	How it works
CI/CD	GitHub Actions triggers on .stitch/next-prompt.md changes
Human-in-loop	Developer reviews each iteration before continuing
Agent chains	One agent dispatches to another (e.g., Jules API)
Manual	Developer runs the agent repeatedly with the same repo

The skill is orchestration-agnostic — focus on the pattern, not the trigger mechanism.

Design System Integration

This skill works best with the design-md skill:

1. First time setup: Generate .stitch/DESIGN.md using the design-md skill from an existing Stitch screen
2. Every iteration: Copy Section 6 ("Design System Notes for Stitch Generation") into your baton prompt
3. Consistency: All generated pages will share the same visual language

Common Pitfalls

• ❌ Forgetting to update .stitch/next-prompt.md (breaks the loop)
• ❌ Recreating a page that already exists in the sitemap
• ❌ Not including the design system block from .stitch/DESIGN.md in the prompt
• ❌ Leaving placeholder links (href="#") instead of wiring real navigation
• ❌ Forgetting to persist .stitch/metadata.json after creating a new project

Troubleshooting

Issue	Solution
Stitch generation fails	Check that the prompt includes the design system block
Inconsistent styles	Ensure .stitch/DESIGN.md is up-to-date and copied correctly
Loop stalls	Verify .stitch/next-prompt.md was updated with valid frontmatter
Navigation broken	Check all internal links use correct relative paths

Limitations

• Use this skill only when the task clearly matches the scope described above.
• Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
• Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.