Build Workflow

A complete system for going from idea to working product — alone, fast, without skipping the thinking.

Built for Cursor and Claude Code. Works for engineers, designers, PMs, or anyone with an idea to ship.

Never installed a developer tool before? Start at Setup — from zero. It takes you from an empty machine to building — one command on your own machine, or zero installs in your browser. Everything below assumes you've done that.

The skills work in any AI-enabled editor or tool — VS Code, Windsurf, or Claude directly. The sequence is what matters, not the platform.

Part of a larger system

Design-workflow is the build process. It works alongside Primitiv — a contract layer that scans your design sources, resolves conflicts between them, and exposes a single source of truth via MCP. Design-workflow gives agents the process. Primitiv gives them the source of truth.

What's inside

build-workflow/
├── .claude/
│   └── commands/               ← Claude Code skills (global)
│       ├── design-thinking.md  ← Problem space + emotional core + brand identity
│       ├── new-project.md      ← Full project scaffolding in one command
│       ├── plan.md             ← Structured planning before building
│       ├── test-debug.md       ← Structured debugging when things break
│       └── evaluate.md         ← Quality gate: correctness, craft, and brand alignment
├── .cursor/
│   └── rules/                  ← Cursor rules (global)
│       ├── ui-design.mdc       ← Visual systems, spacing, typography, components
│       ├── ux-design.mdc       ← UX principles, psychology laws, honest design
│       ├── motion-design.mdc   ← Animation, Framer Motion, reduced motion
│       ├── stack.mdc           ← Opinionated defaults and conventions
│       └── git.mdc             ← Commit conventions, branch strategy
├── docs/
│   └── how-to-use.md           ← The mode sequence, model selection, building in parts
└── install.sh                  ← One-command install

Install

Starting from an empty machine? Don't start here — go to Setup — from zero first. It installs everything below as part of getting you from nothing to building: one command on your own machine, or zero installs in the browser.

Already have Claude Code and a terminal? Install just the skills and rules — clone the repo and run the install script:

git clone https://github.com/AI-by-design/Design-workflow.git
cd Design-workflow
chmod +x install.sh
./install.sh

The script copies Claude Code skills to ~/.claude/commands/ so they work in every project. Then follow the prompts to add the Cursor rules globally.

Manual install

Claude Code skills:

mkdir -p ~/.claude/commands
cp .claude/commands/*.md ~/.claude/commands/

Cursor rules: Open Cursor → Settings → Rules for AI. Paste the contents of each .mdc file from .cursor/rules/ into the global rules field. They apply to every project automatically.

How to use it

Starting a new project

/new-project

Scaffolds everything in one go: Next.js, TypeScript, Tailwind, shadcn/ui, Bun, Git, GitHub repo, and Vercel — plus a CLAUDE.md brief in the project root. Asks three questions first, then handles the rest.

Before writing any code

/design-thinking

Three phases with hard gates between them. Do not skip this.

Phase 1 — Problem Space What breaks, for whom, and when. One sentence, user's words. Locked before moving on.

Phase 2 — Emotional Core How the user feels before, during, and after using the product. This is where brand identity comes from — not a mood board, but the emotional promise the product makes. Four questions: before, during, after, and what it must never feel like.

Phase 3 — Solution Space + Brand Identity The aesthetic direction is derived from the emotional core, not chosen arbitrarily. Every visual decision must be argued, not named. Output: a complete brief written into CLAUDE.md and a project-specific Cursor rule for the visual system.

Every build session that follows works against this brief.

When you're ready to build

/plan

Structured planning before implementation. Breaks the work into phases, surfaces dependencies, flags unknowns before they become blockers.

When something breaks

/test-debug

Structured debugging. Reproduces the problem, isolates the cause, fixes it without breaking anything else.

Before shipping

/evaluate

Audits built output across three layers: automated checks (contrast, spacing, token compliance), UX/UI criteria inherited from the Cursor rules, and LLM judgment on brand alignment and originality. Surfaces all findings before touching anything, waits for confirmation, then fixes blockers only. Run it after any build part is functionally complete — and always after /build-component if you have Primitiv installed. When a Primitiv contract is present, Layer 1 also validates tokens and component names against the contract.

The mode sequence

The workflow starts with a one-time Setup (docs/setup.md) — empty machine to a working AI dev environment — then moves through five build stages. The middle three map to Cursor's Ask, Plan, and Agent modes — but the sequence itself is tool-agnostic and works in Claude Code, VS Code, Windsurf, or any AI-enabled editor.

Setup      →  from zero to a working AI dev environment   (docs/setup.md)
Scaffold   →  /new-project
Ask        →  /design-thinking
Plan       →  /plan
Build      →  /build-component  (from Primitiv) — or build conversationally
Evaluate   →  /evaluate

/test-debug is the sixth skill. Call it any time something breaks — not part of the linear sequence.

Most people skip straight to building. Something comes out. It looks like progress. It isn't — it's chaos that will need unpicking later.

The sequence exists for a reason. Don't skip it.

Scaffold + /new-project Run this once at the start of a new project. It sets up Next.js + TypeScript + Tailwind + shadcn/ui with Bun, initialises git and the GitHub repo, links Vercel, and drops an empty CLAUDE.md shell into the project root. Ends by offering to start /design-thinking and — optionally — primitiv init to install the design contract layer.

Ask + /design-thinking Before you touch anything, invoke /design-thinking. You're not writing code yet. You're making sure you understand what you're building and why — the problem, the person, the feeling the product needs to create. The skill walks you through this in three phases with hard gates between them.

Don't skip this because you think you already know what you want. The skill exists to surface what you don't know you don't know.

Plan + /plan Once /design-thinking is complete and CLAUDE.md has the brief, invoke /plan. The skill breaks the work into parts — frontend, backend, middleware — and then breaks each part into specific tasks.

Be precise. Vague prompts produce vague plans. If the plan doesn't feel right, don't add a new prompt on top of it. Edit the original one. Think it through again.

Build Only start building when the plan is solid. Build one part at a time. Connect as you go. Do not ask the agent to build frontend, backend, and database simultaneously — it produces something that looks like progress but isn't.

If you have Primitiv installed, run /build-component for each UI piece — it loads the design contract, surfaces conflicts, and builds against your real tokens. If you don't have Primitiv, just say "let's build" and the agent walks PLAN.md step by step.

Evaluate + /evaluate After each build part is functionally complete, run /evaluate to quality-gate it before moving on. It audits three layers — automated checks, UX/UI criteria, and brand alignment against your brief. Iterates until blockers pass.

For a deeper guide on the sequence — including how to tighten your plan before building and which model to use for which task — see docs/how-to-use.md.

The CLAUDE.md file

Every project gets a CLAUDE.md in the root. It carries the problem space, emotional core, brand identity, stack decisions, and known patterns for that specific product.

Every Claude Code session opens by reading it. Every Cursor session references it for visual and UX decisions. It's not a README — it's the brief the agent works from.

Created by /new-project. Filled in by /design-thinking. Grows as the project evolves.

The Cursor rules

The craft layer — runs on every file, every project, automatically.

ui-design.mdc — 8pt grid, 60-30-10 colour rule, typography scale, component states, motion patterns, and a self-verification checklist the agent runs before presenting any UI work.

ux-design.mdc — Peter Ramsey / Built for Mars principles, Hick's Law, Peak-end rule, decision architecture, honest design, and structured patterns for empty states, errors, and forms.

motion-design.mdc — what to animate (opacity, transform), what never to animate (width, height, padding), Framer Motion recipes, reduced motion handling.

stack.mdc — Bun over npm always, shadcn/ui before building from scratch, when to add a dependency and when not to.

git.mdc — commit message format, branch naming, what never to commit.

The rules are opinionated. That's the point. They encode decisions so you don't have to make them again.

The philosophy

This workflow is built on the assumption that an agent is only as good as the context you give it.

The design thinking skill ensures the problem is understood before anything is built. CLAUDE.md gives every session the full brief. The Cursor rules give the agent a craft foundation it carries into every file. Together, the system builds like someone who has done this before — not vibe-coding, but deliberate product development.

You don't need to be an engineer to use this. You need to be someone who cares about building the right thing well.

Contributing

This is a living system. If you find something missing, wrong, or improvable — open a PR or an issue. The whole point of sharing it is to make it better.