Skip to content

ADR-0008: Replace ux-expert with stitch-skills pipeline

  • Status: Accepted
  • Date: 2026-03-19
  • Deciders: DeAcero Agentic Team

Context

The design/ux-expert skill provided a generic UX review framework based on Nielsen's 10 heuristics, WCAG 2.1 AA accessibility checks, and structured markdown output. While sound in theory, it had no tooling integration and offered only advisory output — no actionable pipeline for generating, iterating, or shipping UI.

Google Labs published stitch-skills, a suite of 7 Agent Skills built around the Stitch MCP server (Google's AI-powered UI generation tool). These skills form a complete, executable design-to-code pipeline.

Decision

Replace design/ux-expert entirely with the 7 stitch-skills, organized under design/stitch/:

Skill Role in pipeline
stitch-design Unified entry point — orchestrates all design workflows
enhance-prompt Transforms vague ideas into Stitch-optimized prompts
design-md Synthesizes design system into DESIGN.md source of truth
stitch-loop Autonomous iterative site building via baton pattern
react-components Converts Stitch designs to modular React/TypeScript components
shadcn-ui Expert guidance for shadcn/ui + Tailwind integration
remotion Generates walkthrough MP4 videos from Stitch screens

The primary routing entry point is stitch-design, which delegates internally to the other skills as needed.

Rationale

  • ux-expert was [optional] with no explicit routing trigger in AGENTS.md — it was effectively unused
  • stitch-skills are executable: they produce artifacts (screens, components, videos), not just advice
  • All 7 skills follow the same Agent Skills open standard (SKILL.md format), requiring zero structural changes to Cornerstone
  • shadcn-ui and react-components directly serve DeAcero frontend projects scaffolded by Cornerstone

Consequences

Positive

  • Cornerstone projects gain a complete UI generation pipeline out of the box
  • One explicit routing directive covers all frontend/design use cases
  • Skills are maintained upstream by Google Labs — lower maintenance burden

Negative

  • Standalone WCAG/heuristic audits (without Stitch MCP) lose dedicated skill coverage
  • Fallback for pure UX review tasks: use architect or code-reviewer

Dependencies

  • Stitch MCP server must be configured in the consuming project for most skills to function
  • enhance-prompt and shadcn-ui work without Stitch MCP

Implementation

  • Skills copied from upstream SKILL.md files only (resources/, examples/ deferred to a future iteration)
  • Both template source (.agents/skills/) and generated project template ({{cookiecutter.project_slug}}/.agents/skills/) updated
  • All references to ux-expert removed from AGENTS.md, skills.md, INDEX.md, README.md, docs/general_architecture.md