# Phase 1 Retrieval and Networking in stitch::react-components: The 6-Step Gated Workflow

> Understand Phase 1 retrieval and networking in stitch::react-components. Learn the 6-step gated workflow for downloading and auditing Stitch designs before React code generation.

- Repository: [Google Labs Code/stitch-skills](https://github.com/google-labs-code/stitch-skills)
- Tags: deep-dive
- Published: 2026-07-12

---

**Phase 1 retrieval and networking is a mandatory, gated six-step process in the `stitch::react-components` skill that downloads and audits every screen from a Stitch design using official MCP (Machine-Control-Protocol) tools before any React code generation can begin.**

When converting Stitch designs into React components using the `google-labs-code/stitch-skills` repository, Phase 1 retrieval and networking ensures complete design fidelity by enforcing strict download and validation requirements. This phase prevents developers from bypassing remote assets or reusing stale local files, guaranteeing that generated React components remain synchronized with the source Stitch project.

## What Is Phase 1 Retrieval and Networking?

Phase 1 retrieval and networking is the initial mandatory stage defined in [[`SKILL.md`](https://github.com/google-labs-code/stitch-skills/blob/main/SKILL.md)](https://github.com/google-labs-code/stitch-skills/blob/main/plugins/stitch-build/skills/react-components/SKILL.md#L21-L46) that executes whenever the `stitch::react-components` skill converts a Stitch design into code. Unlike ad-hoc file access, this phase requires every screen to be retrieved through authenticated MCP endpoints and validated through manual visual inspection.

The phase operates as a **gated checkpoint**—subsequent stages such as style extraction and component scaffolding remain locked until all six steps complete successfully. This architecture eliminates "cheating" by ensuring no screen can be skipped or sourced from cache without explicit user confirmation.

## The Six-Step Gated Workflow

Phase 1 enforcement follows a strict sequence where each step guards the next. According to the source code analysis, the skill explicitly requires completion of all six actions before marking Phase 1 as finished.

### 1. Namespace Discovery

The process begins by discovering the Stitch MCP prefix to ensure all subsequent calls target the correct protocol namespace.

Run `list_tools` to obtain available MCP prefixes, then isolate the `stitch:` identifier:

```typescript
// Run in the AI-tool environment
const tools = await list_tools();                      // → ["stitch:...", "other:..."]
const stitchPrefix = tools.find(t => t.startsWith('stitch:'));

```

All subsequent MCP invocations must use this discovered prefix. The skill explicitly requires this prefix to be established first; hardcoded prefixes violate the workflow.

### 2. Metadata Fetch for Every Screen

For **every** screen in the project, the skill must call `[prefix]:get_screen` to retrieve JSON payloads containing download URLs.

```typescript
// Assuming stitchPrefix is "stitch:"
const screenId = "screen-abc123";
const screenMeta = await `${stitchPrefix}get_screen`(screenId);
// screenMeta contains htmlCode.downloadUrl and screenshot.downloadUrl

```

The GATE enforcement explicitly states: *"Phase 1 is complete ONLY when all screens have been downloaded."* Skipping any screen breaches this gate and blocks progression.

### 3. Existence Check with Mandatory User Confirmation

Before downloading, the skill checks for existing local copies at `.stitch/designs/{page}.html` and `.stitch/designs/{page}.png`.

If these files exist, the user is **prompted** to either reuse them or refresh them from the MCP. Silent reuse is prohibited—explicit confirmation is mandatory. This prevents accidental consumption of outdated design files.

### 4. High-Reliability Download

The skill delegates actual downloading to the helper script [`scripts/fetch-stitch.sh`](https://github.com/google-labs-code/stitch-skills/blob/main/scripts/fetch-stitch.sh), which handles required query parameters, redirects, and TLS handshakes.

Direct `curl` or other ad-hoc methods are disallowed. The script adds necessary query parameters such as `=w{width}` for high-resolution screenshots:

```bash

# Invoked from the skill's scripts folder

HTML_URL="https://storage.googleapis.com/.../design.html"
PNG_URL="https://storage.googleapis.com/.../screenshot.png"
PAGE="home"

bash scripts/fetch-stitch.sh "$HTML_URL" ".stitch/designs/${PAGE}.html"
bash scripts/fetch-stitch.sh "${PNG_URL}=w${width}" ".stitch/designs/${PAGE}.png"

```

### 5. Visual Audit

After download, the skill requires manual verification of every screenshot. The auditor must open each `.stitch/designs/{page}.png` and confirm that the layout matches the design intent.

Proceeding without viewing every screenshot violates the GATE requirements. This human-in-the-loop verification prevents code generation from corrupted or mismatched assets.

### 6. Project Metadata Tracking

Finally, the skill retrieves overall project configuration via `[prefix]:get_project` and stores it in [`.stitch/metadata.json`](https://github.com/google-labs-code/stitch-skills/blob/main/.stitch/metadata.json) (both in the app folder and workspace root).

```typescript
const projectMeta = await `${stitchPrefix}get_project`();
await writeFile('.stitch/metadata.json', JSON.stringify({
  ...projectMeta,
  LastSyncTime: new Date().toISOString()
}, null, 2));

```

This file must contain `projectId`, `title`, `deviceType`, and a `Last Sync Time` timestamp. Absence or outdated metadata prevents the gate from passing.

## Key Files and Implementation Details

The Phase 1 retrieval and networking logic spans several critical files in the `google-labs-code/stitch-skills` repository:

- **[`plugins/stitch-build/skills/react-components/SKILL.md`](https://github.com/google-labs-code/stitch-skills/blob/main/plugins/stitch-build/skills/react-components/SKILL.md)** — Contains the complete skill definition, Phase 1 description, and GATE enforcement rules.
- **[`plugins/stitch-build/skills/react-components/scripts/fetch-stitch.sh`](https://github.com/google-labs-code/stitch-skills/blob/main/plugins/stitch-build/skills/react-components/scripts/fetch-stitch.sh)** — Bash helper implementing reliable download logic with parameter injection and error handling.
- **[`plugins/stitch-build/skills/react-components/resources/component-template.tsx`](https://github.com/google-labs-code/stitch-skills/blob/main/plugins/stitch-build/skills/react-components/resources/component-template.tsx)** — Template used in subsequent phases (Phase 4) after Phase 1 completes.
- **`.stitch/designs/`** — Runtime directory for downloaded `.html` and `.png` files.
- **[`.stitch/metadata.json`](https://github.com/google-labs-code/stitch-skills/blob/main/.stitch/metadata.json)** — Runtime file tracking project metadata and sync timestamps.

## Summary

Phase 1 retrieval and networking in `stitch::react-components` enforces design fidelity through rigorous gating:

- **Namespace discovery** ensures correct MCP protocol targeting via `list_tools`.
- **Complete metadata fetching** requires every screen to be processed via `get_screen` without exception.
- **Mandatory user confirmation** prevents silent reuse of cached files at `.stitch/designs/`.
- **Script-based downloading** via [`fetch-stitch.sh`](https://github.com/google-labs-code/stitch-skills/blob/main/fetch-stitch.sh) guarantees reliable asset retrieval with proper query parameters.
- **Visual audit requirements** enforce human validation of every screenshot before progression.
- **Metadata tracking** via `get_project` creates audit trails in [`.stitch/metadata.json`](https://github.com/google-labs-code/stitch-skills/blob/main/.stitch/metadata.json) for project synchronization.

Only after satisfying all six gates does the skill unlock Phase 2 (style extraction) and subsequent code generation.

## Frequently Asked Questions

### What happens if I skip a screen during Phase 1 retrieval?

Skipping any screen breaches the "GATE: Phase 1 is complete ONLY when all screens have been downloaded" enforcement defined in [`SKILL.md`](https://github.com/google-labs-code/stitch-skills/blob/main/SKILL.md). The skill will not proceed to style extraction or component generation until every screen is downloaded and audited.

### Can I use cached HTML files instead of downloading from the MCP?

No. While the skill checks for existing files at `.stitch/designs/{page}.html`, it mandates explicit user confirmation before reuse. Silent usage of cached files violates the Phase 1 gate requirements and prevents workflow progression.

### Why does Phase 1 require the [`fetch-stitch.sh`](https://github.com/google-labs-code/stitch-skills/blob/main/fetch-stitch.sh) script instead of direct curl commands?

The [`fetch-stitch.sh`](https://github.com/google-labs-code/stitch-skills/blob/main/fetch-stitch.sh) script (located at [`plugins/stitch-build/skills/react-components/scripts/fetch-stitch.sh`](https://github.com/google-labs-code/stitch-skills/blob/main/plugins/stitch-build/skills/react-components/scripts/fetch-stitch.sh)) handles required query parameters like `=w{width}` for high-resolution screenshots, manages TLS handshakes, and follows redirects reliably. Direct `curl` commands lack these guarantees and are explicitly disallowed by the skill definition.

### Where is the project metadata stored after Phase 1 completes?

Project metadata retrieved via `get_project` is stored in [`.stitch/metadata.json`](https://github.com/google-labs-code/stitch-skills/blob/main/.stitch/metadata.json) in both the app folder and workspace root. This file must include `projectId`, `title`, `deviceType`, and a `Last Sync Time` timestamp to satisfy the final Phase 1 gate.