design-loop

# Design Loop — Autonomous Site Builder

Build complete multi-page websites through an autonomous loop. Each iteration reads a task, generates a page, integrates it, verifies it visually, then writes the next task to keep going.

## Overview

The Design Loop uses a "baton" pattern — a file (`.design/next-prompt.md`) acts as a relay baton between iterations. Each cycle:

1. Reads the current task from the baton
2. Generates the page (via Claude or Google Stitch)
3. Integrates into the site structure (navigation, links)
4. Verifies visually via browser automation (if available)
5. Updates site documentation
6. Writes the NEXT task to the baton — keeping the loop alive

This is orchestration-agnostic. The loop can be driven by:
- **Human-in-loop**: User reviews each page, then says "next" or "keep going"
- **Fully autonomous**: Claude runs continuously until the site is complete
- **CI/CD**: Triggered on `.design/next-prompt.md` changes

## Generation Backends

| Backend | Setup | Quality | Speed | Best for |
|---------|-------|---------|-------|----------|
| **Claude** (default) | Zero dependencies | Great — production-ready HTML/Tailwind | Fast | Most projects, full code control |
| **Google Stitch** | `npm install @google/stitch-sdk` + API key | Higher fidelity AI designs | ~10-20s/screen | Design-heavy projects, visual polish |

### Detecting Stitch

At the start of each loop, check if Stitch is available:

1. Check if `@google/stitch-sdk` is installed: `ls node_modules/@google/stitch-sdk 2>/dev/null`
2. Check if `STITCH_API_KEY` is set in `.dev.vars` or environment
3. Check if `.design/metadata.json` exists (contains Stitch project ID)

If all three are present, use Stitch. Otherwise, fall back to Claude generation.

### Stitch SDK Reference

Install: `npm install @google/stitch-sdk`. Set `STITCH_API_KEY` in environment or `.dev.vars`.

```typescript
import { stitch } from "@google/stitch-sdk";

// Create a project
const result = await stitch.callTool("create_project", { title: "My Site" });

// Reference an existing project
const project = stitch.project("4044680601076201931");

// Generate a screen
const screen = await project.generate("A modern landing page with hero section", "DESKTOP");

// Get assets
const htmlUrl = await screen.getHtml();    // Download URL for HTML
const imageUrl = await screen.getImage();  // Download URL for screenshot

// Edit an existing screen (prefer this for refinements)
const edited = await screen.edit("Make the background dark and enlarge the CTA button");

// Generate variants
const variants = await screen.variants("Try different colour schemes", {
  variantCount: 3,
  creativeRange: "EXPLORE",     // "REFINE" | "EXPLORE" | "REIMAGINE"
  aspects: ["COLOR_SCHEME"],    // "LAYOUT" | "COLOR_SCHEME" | "IMAGES" | "TEXT_FONT" | "TEXT_CONTENT"
});
```

Device types: `"MOBILE"` | `"DESKTOP"` | `"TABLET"` | `"AGNOSTIC"`. Model selection: pass `"GEMINI_3_PRO"` | `"GEMINI_3_FLASH"` as third arg to `generate()`.

Other operations: `stitch.projects()` lists projects, `project.screens()` lists screens, `project.getScreen("id")` fetches one.

`getHtml()` and `getImage()` return download URLs. Append `=w1280` to image URLs for full resolution. Auth: `STITCH_API_KEY` required (or `STITCH_ACCESS_TOKEN` + `GOOGLE_CLOUD_PROJECT` for OAuth). Errors throw `StitchError` with codes: `AUTH_FAILED`, `NOT_FOUND`, `RATE_LIMITED`.

### Stitch Project Persistence

Save Stitch identifiers to `.design/metadata.json` so future iterations can reference them:

```json
{
  "projectId": "4044680601076201931",
  "screens": {
    "index": { "screenId": "d7237c7d78f44befa4f60afb17c818c1" },
    "about": { "screenId": "bf6a3fe5c75348e58cf21fc7a9ddeafb" }
  }
}
```

Stitch integration tips:
1. Persist project ID in `.design/metadata.json` — don't create a new project each iteration
2. Use `screen.edit()` for refinements rather than full regeneration
3. Post-process Stitch HTML — replace headers/footers with your shared elements
4. Include DESIGN.md context in prompts — Stitch generates better results with explicit design system instructions

## Getting Started

### First Run: Bootstrap the Project

If `.design/` doesn't exist yet, create the project scaffolding:

1. **Ask the user** for:
   - Site name and purpose
   - Target audience
   - Desired aesthetic (minimal, bold, warm, etc.)
   - List of pages they want
   - Brand colours (or extract from existing site with `/design-system`)

2. **Create the project files**:

```
project/
├── .design/
│   ├── SITE.md           # Vision, sitemap, roadmap — the project's long-term memory
│   ├── DESIGN.md         # Visual design system — the source of truth for consistency
│   └── next-prompt.md    # The baton — current task with page frontmatter
└── site/
    └── public/           # Production pages live here
```

3. **Write SITE.md** from the template in the "SITE.md Template" section below
4. **Write DESIGN.md** — either manually from user input, or use the `design-system` skill to extract from an existing site
5. **Write the first baton** (`.design/next-prompt.md`) for the homepage

### Subsequent Runs: Read the Baton

If `.design/next-prompt.md` already exists, parse it and continue the loop.

## The Baton File

`.design/next-prompt.md` has YAML frontmatter + a prompt body:

```markdown
---
page: about
layout: standard
---
An about page for Acme Plumbing describing the company's 20-year history in Newcastle.

**DESIGN SYSTEM:**
[Copied from .design/DESIGN.md Section 6]

**Page Structure:**
1. Header with navigation (consistent with index.html)
2. Hero with company photo and tagline
3. Story timeline showing company milestones
4. Team section with photo grid
5. CTA section: "Get a Free Quote"
6. Footer (consistent with index.html)
```

| Field | Required | Purpose |
|-------|----------|---------|
| `page` | Yes | Output filename (without .html) |
| `layout` | No | `standard`, `wide`, `sidebar` — defaults to `standard` |

## Execution Protocol

##