/stitch-loop

name: stitch-loop
description: Iteratively build multi-page websites using Stitch. Reads next-prompt.md (the baton), generates the next page with Stitch MCP, integrates it into the site, then updates next-prompt.md to continue the loop. Works with stitch-design-md and stitch-ui-prompt-architect for consistent multi-page output.
allowed-tools:
  - "stitch*:*"
  - "Bash"
  - "Read"
  - "Write"

Stitch Build Loop

**Constraint:** Only use this skill when the user explicitly mentions "Stitch" and multi-page or iterative site building.

You are an **autonomous frontend builder** in an iterative site-building loop. Each iteration: (1) Read the baton, (2) Generate a page with Stitch MCP, (3) Integrate into the site, (4) Write the next baton so the loop continues.

Prerequisites

• Stitch MCP Server (see `stitch-setup` skill or https://stitch.withgoogle.com/docs/mcp/guide/)
• `DESIGN.md` — generate with `stitch-design-system` from an existing screen (required for consistency)
• `SITE.md` — site vision, Stitch project ID, sitemap, roadmap (create if missing)

The baton system

`next-prompt.md` is the relay baton between iterations. It tells the loop what page to build next.

Baton format

---
page: about
---

**DESIGN SYSTEM (REQUIRED):**
[Paste DESIGN.md Section 6 here verbatim]

**Page request:**
About page with company mission, team section (3 people), and timeline.

**Rules:**

• `page` frontmatter → output filename (`about.html`)
• The body **must** include the design system block from `DESIGN.md` Section 6
• You **must** update `next-prompt.md` at the end of every iteration — the loop stops if this is missing

---

Execution protocol

Step 1 — Read the baton

Parse `next-prompt.md`:

• Extract `page` from YAML frontmatter
• Extract the full prompt body (including the design system block)

Step 2 — Consult context files

| File | What to look for | |------|-----------------| | `SITE.md` | Stitch project ID (Section 2), sitemap (Section 3), roadmap / next pages (Section 4), creative freedom (Section 5) | | `DESIGN.md` | Section 6 — copy this into every prompt, not just the current one |

**Check:** Do not rebuild pages already in `SITE.md` sitemap. Do not deviate from the visual language in `DESIGN.md`.

Step 3 — Generate with Stitch

1. Run `list_tools` → find Stitch MCP prefix 2. If `stitch.json` exists, use stored `projectId` — do not create a new project 3. If no `stitch.json`, call `create_project` → save numeric ID to `stitch.json` 4. Call `generate_screen_from_text`:

• `projectId`: numeric ID (no `projects/` prefix)
• `prompt`: full baton content including DESIGN SYSTEM block
• `deviceType`: match what's in `SITE.md` or `DESIGN.md`

5. Call `get_screen` with numeric projectId + screenId 6. Download HTML: `bash scripts/fetch-stitch.sh "[htmlCode.downloadUrl]" "queue/[page].html"` 7. Download screenshot: save to `queue/[page].png`

Step 4 — Integrate into site

1. Move `queue/[page].html` → `site/public/[page].html` 2. Fix asset paths (make relative to `site/public/`) 3. Wire navigation: replace `href="#"` placeholders with real paths to existing pages 4. Ensure the header/footer matches other pages in the site

Step 4.5 — Visual verification (if Chrome DevTools MCP available)

If `chrome*` tools are in `list_tools`: 1. Start local server: `npx serve site/public -p 3000` 2. Navigate to `http://localhost:3000/[page].html` 3. Take screenshot, compare against `queue/[page].png` 4. Stop server

Step 5 — Update SITE.md

• Add `[x] [page].html` to the sitemap
• Remove consumed ideas from creative freedom section
• Update roadmap if a backlog item was completed

Step 6 — Write the next baton (CRITICAL)

**You must update `next-prompt.md` before completing — the loop stalls if you skip this.**

1. Pick next page from: sitemap → roadmap → creative freedom → or invent one that fits 2. Write `next-prompt.md` with:

• Valid YAML frontmatter (`page: <next-page-name>`)
• `**DESIGN SYSTEM (REQUIRED):**` block copied verbatim from `DESIGN.md` Section 6
• Clear page description

---

File structure

project/
├── next-prompt.md       ← Baton (current task; updated each iteration)
├── stitch.json          ← Stitch project ID (persist between loops!)
├── DESIGN.md            ← From stitch-design-system
├── SITE.md              ← Vision, sitemap, roadmap
├── queue/               ← Staging: [page].html, [page].png
└── site/
    └── public/          ← Production: index.html, about.html, etc.

---

SITE.md template

# Site Vision

[One paragraph describing the site's purpose, audience, and overall feeling]

## Stitch Project

- **Project ID (numeric):** [ID from stitch-mcp-create-project]

## Sitemap

- [ ] index.html — Home
- [ ] about.html — About
- [ ] contact.html — Contact

## Roadmap

1. index.html — main landing page
2. about.html — company/team info
3. contact.html — contact form

## Creative freedom

Additional pages or sections not yet planned...

---

Common pitfalls

• ❌ Forgetting to update `next-prompt.md` (loop stops)
• ❌ Rebuilding a page already in SITE.md sitemap
• ❌ Omitting `DESIGN.md` Section 6 from the prompt (causes visual drift)
• ❌ Using `projects/ID` format instead of numeric in `generate_screen_from_text`
• ❌ Leaving `href="#"` instead of wiring real page links
• ❌ Not persisting `stitch.json` (creates new project every iteration)

---

Troubleshooting

| Issue | Fix | |-------|-----| | Inconsistent visual styles across pages | Keep DESIGN.md updated; always copy Section 6 into baton | | Loop stalls at next iteration | Check `next-prompt.md` has valid frontmatter and non-empty body | | Stitch generation fails | Ensure baton includes DESIGN SYSTEM block and a specific page request | | Broken navigation | Use relative paths for internal links; check `site/public/` structure |

---

References

• `scripts/fetch-stitch.sh` — Reliable GCS HTML downloader
• `stitch-design-