ce-design-flow

A design leg for the Compound Engineering loop, powered by Open Design.

Compound Engineering is very good at what problem are we solving and has nothing to say about what should this look like. So you find out the thing is ugly after the MVP exists — the most expensive possible moment.

This plugin adds the missing leg. You get a design decision, made and approved, before any code is written, and a screenshot-backed check that the build didn't drift away from it.

/ce-design "<pain point>"
       │
       ├─ 0. brainstorm ──────────── upstream ce-brainstorm, unmodified
       │
       ├─ 1. design ──────────────── N wireframes in parallel
       │        │                    → you pick (real gate, it stops for you)
       │        │                    → hi-fi mockup
       │        └─ at every gate: a live browser portal you can chat in and mark up,
       │                          then one line in the terminal to continue
       │
       ├─ 2. plan ────────────────── upstream ce-plan, with the mockup written into
       │                             the acceptance criteria
       │
       └─ 3. build ──────────────── ce-work, then screenshot vs mockup, name every
                                     deviation, fix

What makes it different from "ask Claude for a UI"

• You see three structural options before committing to one. Same data model, different structure — so you are comparing structure, not content.
• The design becomes an acceptance criterion, not a memory. The mockup path and its screenshot go into the plan, and the build gets checked against them.
• The human stays in the loop where it matters and nowhere else. One real gate (pick a direction). Everything after it is automatic until you interrupt.
• Screenshots are the acceptance test. Type checks, tests, and HTML validation all pass layout defects; in the runs behind this plugin, 2 of 3 hi-fi artifacts shipped defects that every automated check missed.
• It compounds. Every trap hit gets written into design-lessons.md as a constraint you paste into the next prompt. Hit it once, be immune afterwards.

Install

1. Install Open Design and make sure its daemon runs — https://github.com/nexu-io/open-design. The CLI ships as od; many people symlink it to od-design to avoid colliding with the POSIX od. Both work here.

2. Install the Compound Engineering plugin (this one wraps it, it does not replace it):

/plugin marketplace add EveryInc/compound-engineering-plugin
/plugin install compound-engineering

3. Install this plugin:

/plugin marketplace add waveriderai/ce-design-flow
/plugin install ce-design-flow

4. Check your environment before your first run — a wireframe run takes ~20 minutes, so you want to find problems now, not then:

scripts/preflight.sh

It resolves your Open Design binary, checks the daemon, confirms the templates this route needs are installed, performs a real MCP handshake, and — the one people always hit — tells you whether the portal URL you hand a human is actually reachable from their browser.

Use

Command	What happens
/ce-design <pain point>	The full route: brainstorm → design → plan
/ce-design <path to a requirements doc>	Skip brainstorm, design from an existing spec
/ce-markup	Open the current artifact in the browser portal, then resume cleanly when you come back
/ce-brainstorm <pain point>	Upstream CE, no design leg — for backend/CLI work

Whether design happens is decided by which command you type. The flow never stops to ask "should we design this?".

The portal round trip

This is the part that makes it feel like a design tool rather than a prompt.

At every design gate the agent prints a URL and stops. You open it and get a live, editable workspace — not a screenshot:

• chat with the agent in the composer ("move the safe area to the top")
• click an element and mark it up with a comment describing the change
• edit the artifact directly

Your edits save straight to the project file on disk. When you're done you go back to the terminal and say one line — "direction B, go to hi-fi" — and the agent re-reads the file from disk and re-screenshots before continuing, so nothing you did in the browser is lost.

That last sentence is the entire reason /ce-markup exists as a skill. The failure mode isn't opening a browser; it's an agent that continues from its stale memory of a file you just changed.

Adapting it to your setup

The route is deliberately built out of substitutable parts:

You want to change	Do this
The inner model	Pin --agent / --model on runs. Open Design relays your agent CLI's model list, so update the CLI to get new models — the daemon queries live and needs no restart
Your brand	Set --design-system <id> at project creation. Built-ins (stripe, linear-app, vercel, …), your own user:<id>, or extract one from a URL with od brand extract
Fidelity / artifact kind	Swap the template id: wireframe-mobile-flow for mobile, wireframe-annotated for redlines, example-web-prototype-taste-{brutalist,editorial,soft} for hi-fi flavor
How many directions	N directions = N projects = N parallel runs. Three is a good default; there is nothing special about three
Your own lessons	Append to skills/ce-design/references/design-lessons.md. That file is the point — it is where the loop compounds
Not using Compound Engineering	The design stage stands alone. Drop stages 0 and 2 and you still get wireframes → pick → hi-fi → screenshot acceptance

What's in here

skills/ce-design/         the orchestrator: entry routing, stages 0-4, iron rules
  references/
    portal-handoff.md     browser ↔ terminal round trip, with the resume checklist
    prompt-armor.md       copy-paste blocks that stop known failure modes
    design-lessons.md     the compounding file — 13 traps and the constraints they produced
    open-design-map.md    Open Design's surface: commands, template ids, model pinning
    preflight.md          what each environment check means
    anti-rationalization.md  the excuses for skipping the rules, and why each is wrong
  assets/compare-template.html   side-by-side page for the pick gate
skills/ce-markup/         the portal round trip as a re-entrant step
scripts/
  preflight.sh            environment check
  od-host.sh              resolves the portal host (the localhost-over-SSH trap)
  od_mcp.py               one-shot MCP calls from a shell
examples/reading-list/    a real run: brief, artifacts, screenshots, timings

The worked example is not a highlight reel. It is one real run of the route, and the hi-fi artifact it produced contains a genuine layout defect — a chart label silently truncated to fit — which was inherited from the wireframe stage and which every automated check passes. The defect is left in and analyzed, because an example where everything came out clean would teach you the wrong thing about what these runs produce.

Known limits

Stated plainly, because finding these out yourself is expensive:

• A run takes real time. Measured: 6–25 min per wireframe depending on brief complexity, ~8–13 min per hi-fi. They parallelize, but this is not an interactive loop.
• It depends on the names ce-brainstorm and ce-plan existing in the Compound Engineering plugin. If upstream renames them, this degrades gracefully — you land in ce-brainstorm's own handoff menu — rather than breaking. It deliberately does not depend on their phase numbers, menu wording, or internal headings.
• Nothing upstream calls this plugin. Finishing a CE plan does not auto-start a design. You type /ce-design, or Claude picks it up from the skill description.
• Importing an existing non-Open-Design product (your live site, a Figma file) into this route is not verified here. od project import-folder exists and is the obvious start.
• Lessons were captured against Open Design 0.14.x with Codex as the inner agent. The structural ones should hold; ids and model slugs will drift. Every table that can go stale ships with the command to re-derive it.

Credits

This plugin is a wrapper. It modifies no upstream file, and it would not exist without:

• Compound Engineering by Kieran Klaassen and Trevin Chow at Every — the brainstorm → plan → work → review → compound loop this hangs a design leg onto. MIT. The idea that each unit of work should make the next one easier is theirs, and design-lessons.md is a direct application of it.
• Open Design by nexu-io — the local-first design workspace that does all the actual design work here: templates, design systems, the artifact runtime, and the browser portal. Apache-2.0.

Full attribution and licensing in CREDITS.md.

License

MIT — see LICENSE. The upstream projects keep their own licenses; nothing from them is vendored here.