System · Harbor

Agent stack

MCP · markdown · skills — why we ship all three and lead with MCP.

stack.md

Agent stack — law book · skills · fail-closed gates · optional MCP

Lead with what agents cannot skip.
Design contracts are fail-closed systems — not mood boards, not protocol theater.

This is the product architecture behind ui.byronwade.com. Marketing and agents should tell the same story.

The short answer

Layer	Required?	Job
design.md · agents.md · DNA docs	Yes — law book	Persistent why, load order, negatives, per-contract identity
Skills (verified adapters)	Yes — cookbook	Exhaustive playbooks grounded in real primitives / recipes
Fail-closed gates	Yes — bailiff	ESLint + `check:*` + CI — agents fail the PR when they freestyle
Contract MCP	Optional accelerator	Queryable kit + `validate_ui` for tool-calling agents
shadcn MCP / CLI	Optional	Atom delivery only — not design law

Do not ship vibes alone. Markdown without gates drifts. Skills without catalogs invent twins. MCP without local lint is opt-in folklore.

Why this order (research-backed)

v0 Design Systems 2.0 teaches systems as a skill adapter grounded in real source + a verified starter — not as a docs dump and not as MCP-first protocol.

DESIGN.md is portable identity (tokens + prose + don’t-rules). It is necessary and lintable — and still skippable unless CI fails.

MCP tool schemas cost context (CircleCI on MCP vs CLI). Design-system obedience is mostly local: imports, classnames, forbidden patterns. Linters and scripts outperform agents for deterministic checks (The Design System Guide).

Fail-closed loop (every contract)

Load this contract’s design.md + agents.md (always-on rules / AGENTS.md)
Open the matching skill ({id}-compose, {id}-theme, …) — verified APIs only
Prefer a task recipe over freeform layout (list-resource, agent-rail, …)
Compose approved shadcn primitives — never twin Buttons/Cards/shells
Run npm run validate (or at least check:design + check:platform + check:contrast) before done
Optionally call contract MCP get_contract / validate_ui when the agent is tool-wired

Per-contract DNA

Contract	Feeling	Skill prefix
Meridian	Cinematic warm paper · ink-teal · full-bleed frames	`meridian-*`
Harbor	Quiet ops paper · semantic status · dense indexes	`harbor-*`
Atlas	Ink workbench · mono metadata · keyboard-first	`atlas-*`
Vellum	Mist reading lanes · measured prose · typeset-first	`vellum-*`

Structure (routes, machine filenames, recipe ids, JSON keys) is shared via lib/platform/skeleton.ts. Aesthetics and skill cookbooks may differ. See platform.md.

Comparison (honest)

Approach	Strength	Failure mode
DESIGN.md only	Portable rationale	Agents skip; no PR fail
Skills only	Great procedures	Opt-in; invent APIs without catalogs
MCP only	Queryable tools	Context tax; agents skip tools
shadcn MCP only	Atom install	No brand / ban / recipe law
Law book + verified skills + CI gates (+ optional MCP)	Context + procedure + enforcement	Slightly more surface — intentional

What is not the wedge

Marketing MCP as the only way to stay on-system
Freeform theme playgrounds as product prefs
Forking MCP tools or JSON keys per DNA
Twin component kits “just for this screen”

Golden path

Pick a contract on the platform catalog (/)
Open /{id} — the page is the DNA
Install skills: npx skills add byronwade/ui.byronwade.com
Copy design.md / agents.md (or fetch /{id}/design.md?raw=1)
Wire always-on AGENTS / Cursor rules
Agent loop: law book → skill → recipe → compose → validate
Optional: add contract MCP for tool-calling sessions