1---
2name: stitch-loop
3description: Teaches agents to iteratively build websites using Stitch with an autonomous baton-passing loop pattern
4allowed-tools:
5  - "stitch*:*"
6  - "chrome*:*"
7  - "Read"
8  - "Write"
9  - "Bash"
10---
11 
12# Stitch Build Loop
13 
14You 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.
15 
16## Overview
17 
18The Build Loop pattern enables continuous, autonomous website development through a "baton" system. Each iteration:
191. Reads the current task from a baton file (`.stitch/next-prompt.md`)
202. Generates a page using Stitch MCP tools
213. Integrates the page into the site structure
224. Writes the next task to the baton file for the next iteration
23 
24## Prerequisites
25 
26**Required:**
27- Access to the Stitch MCP Server
28- A Stitch project (existing or will be created)
29- A `.stitch/DESIGN.md` file (generate one using the `design-md` skill if needed)
30- A `.stitch/SITE.md` file documenting the site vision and roadmap
31 
32**Optional:**
33- Chrome DevTools MCP Server — enables visual verification of generated pages
34 
35## The Baton System
36 
37The `.stitch/next-prompt.md` file acts as a relay baton between iterations:
38 
39```markdown
40---
41page: about
42---
43A page describing how jules.top tracking works.
44 
45**DESIGN SYSTEM (REQUIRED):**
46[Copy from .stitch/DESIGN.md Section 6]
47 
48**Page Structure:**
491. Header with navigation
502. Explanation of tracking methodology
513. Footer with links
52```
53 
54**Critical rules:**
55- The `page` field in YAML frontmatter determines the output filename
56- The prompt content must include the design system block from `.stitch/DESIGN.md`
57- You MUST update this file before completing your work to continue the loop
58 
59## Execution Protocol
60 
61### Step 1: Read the Baton
62 
63Parse `.stitch/next-prompt.md` to extract:
64- **Page name** from the `page` frontmatter field
65- **Prompt content** from the markdown body
66 
67### Step 2: Consult Context Files
68 
69Before generating, read these files:
70 
71| File | Purpose |
72|------|---------|
73| `.stitch/SITE.md` | Site vision, **Stitch Project ID**, existing pages (sitemap), roadmap |
74| `.stitch/DESIGN.md` | Required visual style for Stitch prompts |
75 
76**Important checks:**
77- Section 4 (Sitemap) — Do NOT recreate pages that already exist
78- Section 5 (Roadmap) — Pick tasks from here if backlog exists
79- Section 6 (Creative Freedom) — Ideas for new pages if roadmap is empty
80 
81### Step 3: Generate with Stitch
82 
83Use the Stitch MCP tools to generate the page:
84 
851. **Discover namespace**: Run `list_tools` to find the Stitch MCP prefix
862. **Get or create project**: 
87   - If `.stitch/metadata.json` exists, use the `projectId` from it
88   - 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)
89   - 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)
903. **Generate screen**: Call `[prefix]:generate_screen_from_text` with:
91   - `projectId`: The project ID
92   - `prompt`: The full prompt from the baton (including design system block)
93   - `deviceType`: `DESKTOP` (or as specified)
944. **Retrieve assets**: Before downloading, check if `.stitch/designs/{page}.html` and `.stitch/designs/{page}.png` already exist:
95   - **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.
96   - **If files do not exist**: Proceed with download:
97     - `htmlCode.downloadUrl` — Download and save as `.stitch/designs/{page}.html`
98      - `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`
99 
100### Step 4: Integrate into Site
101 
1021. Move generated HTML from `.stitch/designs/{page}.html` to `site/public/{page}.html`
1032. Fix any asset paths to be relative to the public folder
1043. Update navigation:
105   - Find existing placeholder links (e.g., `href="#"`) and wire them to the new page
106   - Add the new page to the global navigation if appropriate
1074. Ensure consistent headers/footers across all pages
108 
109### Step 4.5: Visual Verification (Optional)
110 
111If the **Chrome DevTools MCP Server** is available, verify the generated page:
112 
1131. **Check availability**: Run `list_tools` to see if `chrome*` tools are present
1142. **Start dev server**: Use Bash to start a local server (e.g., `npx serve site/public`)
1153. **Navigate to page**: Call `[chrome_prefix]:navigate` to open `http://localhost:3000/{page}.html`
1164. **Capture screenshot**: Call `[chrome_prefix]:screenshot` to capture the rendered page
1175. **Visual comparison**: Compare against the Stitch screenshot (`.stitch/designs/{page}.png`) for fidelity
1186. **Stop server**: Terminate the dev server process
119 
120> **Note:** This step is optional. If Chrome DevTools MCP is not installed, skip to Step 5.
121 
122### Step 5: Update Site Documentation
123 
124Modify `.stitch/SITE.md`:
125- Add the new page to Section 4 (Sitemap) with `[x]`
126- Remove any idea you consumed from Section 6 (Creative Freedom)
127- Update Section 5 (Roadmap) if you completed a backlog item
128 
129### Step 6: Prepare the Next Baton (Critical)
130 
131**You MUST update `.stitch/next-prompt.md` before completing.** This keeps the loop alive.
132 
1331. **Decide the next page**: 
134   - Check `.stitch/SITE.md` Section 5 (Roadmap) for pending items
135   - If empty, pick from Section 6 (Creative Freedom)
136   - Or invent something new that fits the site vision
1372. **Write the baton** with proper YAML frontmatter:
138 
139```markdown
140---
141page: achievements
142---
143A competitive achievements page showing developer badges and milestones.
144 
145**DESIGN SYSTEM (REQUIRED):**
146[Copy the entire design system block from .stitch/DESIGN.md]
147 
148**Page Structure:**
1491. Header with title and navigation
1502. Badge grid showing unlocked/locked states
1513. Progress bars for milestone tracking
152```
153 
154## File Structure Reference
155 
156```
157project/
158├── .stitch/
159│   ├── metadata.json   # Stitch project & screen IDs (persist this!)
160│   ├── DESIGN.md       # Visual design system (from design-md skill)
161│   ├── SITE.md         # Site vision, sitemap, roadmap
162│   ├── next-prompt.md  # The baton — current task
163│   └── designs/        # Staging area for Stitch output
164│       ├── {page}.html
165│       └── {page}.png
166└── site/public/        # Production pages
167    ├── index.html
168    └── {page}.html
169```
170 
171### `.stitch/metadata.json` Schema
172 
173This 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.
174 
175```json
176{
177  "name": "projects/6139132077804554844",
178  "projectId": "6139132077804554844",
179  "title": "My App",
180  "visibility": "PRIVATE",
181  "createTime": "2026-03-04T23:11:25.514932Z",
182  "updateTime": "2026-03-04T23:34:40.400007Z",
183  "projectType": "PROJECT_DESIGN",
184  "origin": "STITCH",
185  "deviceType": "MOBILE",
186  "designTheme": {
187    "colorMode": "DARK",
188    "font": "INTER",
189    "roundness": "ROUND_EIGHT",
190    "customColor": "#40baf7",
191    "saturation": 3
192  },
193  "screens": {
194    "index": {
195      "id": "d7237c7d78f44befa4f60afb17c818c1",
196      "sourceScreen": "projects/6139132077804554844/screens/d7237c7d78f44befa4f60afb17c818c1",
197      "x": 0,
198      "y": 0,
199      "width": 390,
200      "height": 1249
201    },
202    "about": {
203      "id": "bf6a3fe5c75348e58cf21fc7a9ddeafb",
204      "sourceScreen": "projects/6139132077804554844/screens/bf6a3fe5c75348e58cf21fc7a9ddeafb",
205      "x": 549,
206      "y": 0,
207      "width": 390,
208      "height": 1159
209    }
210  },
211  "metadata": {
212    "userRole": "OWNER"
213  }
214}
215```
216 
217| Field | Description |
218|-------|-------------|
219| `name` | Full resource name (`projects/{id}`) |
220| `projectId` | Stitch project ID (from `create_project` or `get_project`) |
221| `title` | Human-readable project title |
222| `designTheme` | Design system tokens: color mode, font, roundness, custom color, saturation |
223| `deviceType` | Target device: `MOBILE`, `DESKTOP`, `TABLET` |
224| `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`) |
225| `metadata.userRole` | User's role on the project (`OWNER`, `EDITOR`, `VIEWER`) |
226 
227## Orchestration Options
228 
229The loop can be driven by different orchestration layers:
230 
231| Method | How it works |
232|--------|--------------|
233| **CI/CD** | GitHub Actions triggers on `.stitch/next-prompt.md` changes |
234| **Human-in-loop** | Developer reviews each iteration before continuing |
235| **Agent chains** | One agent dispatches to another (e.g., Jules API) |
236| **Manual** | Developer runs the agent repeatedly with the same repo |
237 
238The skill is orchestration-agnostic — focus on the pattern, not the trigger mechanism.
239 
240## Design System Integration
241 
242This skill works best with the `design-md` skill:
243 
2441. **First time setup**: Generate `.stitch/DESIGN.md` using the `design-md` skill from an existing Stitch screen
2452. **Every iteration**: Copy Section 6 ("Design System Notes for Stitch Generation") into your baton prompt
2463. **Consistency**: All generated pages will share the same visual language
247 
248## Common Pitfalls
249 
250- ❌ Forgetting to update `.stitch/next-prompt.md` (breaks the loop)
251- ❌ Recreating a page that already exists in the sitemap
252- ❌ Not including the design system block from `.stitch/DESIGN.md` in the prompt
253- ❌ Leaving placeholder links (`href="#"`) instead of wiring real navigation
254- ❌ Forgetting to persist `.stitch/metadata.json` after creating a new project
255 
256## Troubleshooting
257 
258| Issue | Solution |
259|-------|----------|
260| Stitch generation fails | Check that the prompt includes the design system block |
261| Inconsistent styles | Ensure `.stitch/DESIGN.md` is up-to-date and copied correctly |
262| Loop stalls | Verify `.stitch/next-prompt.md` was updated with valid frontmatter |
263| Navigation broken | Check all internal links use correct relative paths |
264