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

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/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:

// 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.

// 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, 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:

# 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 (both in the app folder and workspace root).

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 — Contains the complete skill definition, Phase 1 description, and GATE enforcement rules.
• 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 — Template used in subsequent phases (Phase 4) after Phase 1 completes.
• .stitch/designs/ — Runtime directory for downloaded .html and .png files.
• .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 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 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. 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 script instead of direct curl commands?

The fetch-stitch.sh script (located at 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}