StitchFlow

Turn product briefs into Google Stitch projects, UI directions, design systems, HTML handoff artifacts, screenshots, and regression evidence from one portable agent workflow.

StitchFlow is for teams that want Stitch to stay the design source of truth while agents handle the repeatable work around it: prompt shaping, variants, DESIGN.md, design-system application, local exports, audits, and release checks.

StitchFlow live workflow demo

Why Use It

• One workflow across agent clients: Codex, Claude Code, OpenClaw, GitHub

Copilot, Gemini CLI, and clients that understand SKILL.md / AGENTS.md.

• Native MCP first, local CLI fallback: use live Stitch MCP tools when your

client exposes them; otherwise use the bundled stitch-starter toolkit.

• Local evidence by default: save HTML, screenshots, result.json,

variants.json, export manifests, and audit reports under runs/.

• Design-system coverage: upload DESIGN.md, create/list/update/apply

Stitch design systems, and regression-test the full design-system path.

• Handoff checks: audit required text, unsupported claims, artifact quality,

responsive overflow, browser errors, and serious accessibility issues.

• Safe project downloads: use the SDK downloader when possible and fall back

to short local paths when long Stitch screen titles hit filesystem limits.

Requirements

• Node.js >=22
• A Google Stitch API key in STITCH_API_KEY
• At least one supported agent client or direct CLI usage

Secrets stay local. The installer preserves an existing toolkit .env, and the toolkit .gitignore excludes .env, runs/, and node_modules/.

Install

git clone https://github.com/yshishenya/stitchflow.git
cd stitchflow
bash install.sh --target all

Add your API key:

${STITCH_STARTER_ROOT:-$HOME/.agents/stitch-starter}/.env

Then restart your agent client.

Canonical install paths:

Quick Start

In Codex:

Use $stitchflow to generate a premium desktop analytics dashboard for a product team, with a left sidebar, KPI cards, trend charts, and clean Tailwind-ready HTML.

In Claude Code:

/stitchflow landing page for a design tool aimed at enterprise product teams

In OpenClaw:

Use the stitchflow skill to explore three mobile-first UI directions for a checkout experience.

Direct CLI:

cd "${STITCH_STARTER_ROOT:-$HOME/.agents/stitch-starter}"
npm run generate -- --prompt "A modern SaaS dashboard with sidebar and stat cards"
npm run variants -- --prompt "Explore three different visual directions" --variant-count 3
npm run edit -- --prompt "Make spacing calmer and strengthen the primary CTA"

Outputs are written to:

${STITCH_STARTER_ROOT:-$HOME/.agents/stitch-starter}/runs/<timestamp>-<operation>-<slug>/

Native Stitch MCP

When available, StitchFlow prefers native Stitch MCP tools such as create_project, generate_screen_from_text, edit_screens, generate_variants, upload_design_md, create_design_system_from_design_md, apply_design_system, and get_screen.

Codex MCP example:

[mcp_servers.stitch]
url = "https://stitch.googleapis.com/mcp"
enabled = true

[mcp_servers.stitch.http_headers]
"X-Goog-Api-Key" = "<your Stitch API key>"

Restart the client after changing MCP config.

CLI Toolkit

Run these from ${STITCH_STARTER_ROOT:-$HOME/.agents/stitch-starter}:

Useful examples:

npm run generate -- --prompt "A cinematic product homepage" --model-id GEMINI_3_1_PRO --timeout-ms 900000
npm run design-system -- --action apply --project-id 123 --asset-id 456 --screen-ids abc,def
npm run download-project -- --project-id 123
npm run download-project -- --project-id 123 --safe-download
npm run site-design-audit -- --file ./site-design-audit.json
npm run regression:e2e -- --timeout-ms 900000 --model-id GEMINI_3_FLASH

See Local CLI Usage for every flag and workflow boundary.

Website Design Workflow

For full site work, StitchFlow does not jump from one generated homepage to implementation. The workflow is:

1. Capture product context and screen inventory.
2. Generate or record logo directions when brand identity is open.
3. Create at least five homepage candidates.
4. Record the selected homepage screen id and rationale.
5. Generate the remaining screens from the selected visual direction.
6. Export approved screens and run download-project.
7. Audit handoff coverage, artifacts, content truth, responsive behavior, and

accessibility.

Start with Site Design Delivery.

Validation

Local static checks:

cd stitch-starter
npm ci
for script in scripts/*.mjs; do node --check "$script"; done
npm run site-design-audit -- --file /path/to/site-design-audit.json --check-project false

Installer check:

bash install.sh --target all --skip-smoke --skip-npm

Live release regression:

cd stitch-starter
npm run regression:e2e -- --timeout-ms 900000 --retries 1 --retry-delay-ms 3000 --model-id GEMINI_3_FLASH

The full site-design E2E is intentionally heavier. It uses a parent/worker wrapper so --total-timeout-ms can kill a stuck live worker process:

npm run site-design:e2e -- --brand "Turnirka" --timeout-ms 900000 --operation-timeout-ms 900000 --total-timeout-ms 3600000

Documentation

• Skill instructions
• CLI reference
• Prompt keywords
• Text to design
• Edit design
• Variants
• Project prototype export
• Site design delivery
• Toolkit README
• Changelog

Distribution

• Agent skill: skills/stitchflow/SKILL.md
• Legacy alias: skills/stitch-design-local/SKILL.md
• Codex/OpenClaw/Claude-compatible install: install.sh
• GitHub Copilot plugin manifest: .github/plugin/plugin.json
• Gemini CLI extension manifest: gemini-extension.json
• Catalog checklist: docs/catalog-submissions.md

Release Policy

StitchFlow uses semantic versioning. Backward-compatible feature additions are minor releases; backward-compatible fixes are patch releases; breaking workflow or CLI contract changes require a major release.

Every release should include:

• updated manifests and skill metadata
• a focused changelog entry
• local static validation
• live regression:e2e evidence
• a GitHub release generated from the tag and checked against the changelog

Contributing

Read CONTRIBUTING.md, open a focused pull request, and include validation evidence. Do not commit STITCH_API_KEY, .env, generated runs/, or node_modules/.

License

Apache-2.0. See LICENSE.