nano-step/od-workflow

od-workflow

A turn-by-turn Open Design playbook for OpenCode subagents. Transcribed from nexu-io/open-design (Apache 2.0; see ATTRIBUTION.md) and adapted to use this repo's od_* MCP tools.

Overview

open-design-mcp ships 10 stateless MCP tools. They're hands, not a brain. This skill is the brain: a multi-turn workflow that drives an LLM through OD's full design arc using a combination of OpenCode's native tools (TodoWrite / Read / Write / Bash / WebFetch / Glob / Grep) and our od_* MCP tools.

The architecture:

User: "Make me a SaaS landing page"
   ↓
OpenCode loads this skill (trigger keywords match)
   ↓
LLM follows the 3-rule playbook below
   ↓
Turn 1: ask discovery questions, stop
Turn 2: extract brand spec OR pick a direction
Turn 3+: TodoWrite plan → build → checklist → critique → emit artifact
   ↓
Result: a polished, consistent, briefed design

The MCP tools (od_create_project, od_generate_design, od_save_artifact, etc.) are primitives the LLM calls during turn 3+. This skill teaches the LLM when to call them and what to pass — not how the daemon works.

When to use this skill

| Trigger | Examples | |---|---| | User starts a new design project | "make me a landing page", "design a pitch deck", "build a SaaS prototype" | | User mentions brand consistency | "match my brand", "all pages should look like one product" | | User provides brand context | "here's our brand URL", "match this screenshot" | | User wants full quality flow | "be thorough", "ask me questions", "do it properly" |

| Anti-trigger (use od_generate_design directly instead) | Examples | |---|---| | Tweaking an existing artifact | "make the nav stickier", "change the copy in section 2" | | Single trivial section | "give me a 200-word hero copy block" | | Pure render request | "generate the HTML for this exact spec" (no design decisions needed) |

The 3-rule playbook

These are the hard rules. They are not optional. The user is paying attention to speed of feedback; obeying these rules is what makes the workflow feel responsive instead of stuck.

RULE 1 — Turn 1: emit a discovery form, then stop

Transcribed from upstream discovery.ts:33-119 (Apache 2.0). Full text in references/discovery-form.md.

When the user opens a new project or sends a fresh design brief, the very first output is one short prose line + a <question-form> block. Nothing else. No file reads. No Bash. No od_generate_design. No extended thinking. The form is the time-to-first-byte.

The form has 7 standard questions: output, platform, audience, tone, brand, scale, constraints. Exact JSON schema in references/discovery-form.md. Tailor the questions to the brief — drop defaults the user already answered, add fields the brief uniquely needs.

After </question-form>, stop the turn. Wait for [form answers — discovery] on the next user message.

Skip the form only in these narrow cases:

• User is replying inside an active design with a tweak
• User explicitly says "skip questions" / "just build"
• User's message starts with [form answers — ...] (already have answers)

In OpenCode (no form-rendering UI): if the host environment does not render <question-form> markup as interactive UI, ask the same questions conversationally. The 7 questions are the same; the wire format is just chat text. See references/discovery-form.md §"How to ask these questions in an LLM-driven flow".

RULE 2 — Turn 2: branch on the brand answer

Transcribed from upstream discovery.ts:121-151 (Apache 2.0). Full text in references/brand-extraction.md.

Once the user submits the form (or the initial brief already answered the brand question), resolve the branch:

| Brand answer | Action | |---|---| | "brand_spec" or "reference_match" + a source URL/file provided | Branch A: run brand-spec extraction (5 steps below) | | "brand_spec" or "reference_match" but no source provided | Ask the user to paste/upload the spec, then stop. Do NOT guess. | | "pick_direction" or no brand answer | Branch B: pick the best-matching direction from references/direction-library.md. Do NOT emit a second direction-picking form. |

Branch A — 5-step brand extraction (each step is its own tool call):

1. Locate the source. List attached files OR WebFetch brand URLs (<brand>.com/brand, /press, /about).
2. Download styling artifacts. Their CSS, brand-guide PDFs, screenshots — whatever's available.
3. Extract real values. Bash grep -E '#[0-9a-fA-F]{3,8}' on CSS for hex colors. Eyeball screenshots for typography. Never guess colors from memory.
4. Codify. Write brand-spec.md to the project root with 6 OKLch color tokens + display/body/mono font stacks + 3-5 layout posture rules. Template in references/brand-extraction.md.
5. Vocalize. State the system in one sentence ("deep navy product canvas, single electric-cyan accent at oklch(68% 0.16 220), geometric display + system body") so the user can redirect cheaply.

Then proceed to RULE 3.

RULE 3 — Turn 3+: TodoWrite the plan, then live updates

Transcribed from upstream discovery.ts:155-195 (Apache 2.0). Full text in references/plan-and-critique.md.

Once the brand/direction is locked, the first tool call is TodoWrite with 5–10 short imperative items in the order to execute. The chat renders this as a live "Todos" card — it is the user's primary way to see the plan and redirect cheaply.

Standard plan template:

1. Read active DESIGN.md + skill assets (template.html, layouts.md, checklist.md)
2. (Branch A) Confirm brand-spec.md + bind to :root
   (Active DESIGN.md) Bind active design-system tokens to :root
   (Branch B) Pick a direction from the library, bind to :root
3. Plan section/slide/screen list with platform variants and rhythm
4. od_create_project { id: "<short-slug>", name, customInstructions: <brand spec> } (if no projectId yet — `id` is REQUIRED, regex `/^[A-Za-z0-9._-]{1,128}$/`)
5. For each section/screen: od_generate_design { projectId, prompt, maxTokens? }
6. Replace any [REPLACE] placeholders with real, specific copy from the brief
7. Self-check: run the P0 anti-AI-slop checklist (every P0 must pass)
8. 5-dim critique: philosophy / hierarchy / execution / specificity / restraint; fix any dimension < 3/5
9. od_lint_artifact { html: <full HTML> } + od_save_artifact { identifier, title, html } for each section
9b. (optional) od_save_project_file { projectId, name: "index.html", content: <html> } to save the file inside the project so it renders in the daemon UI (use instead of or in addition to od_save_artifact; see "od_save_project_file vs od_save_artifact" below)

After TodoWrite, immediately mark step 1 in_progress. As each step completes, update — do NOT batch updates at the end of the turn; the live progress is the point.

Step 7 (checklist) and Step 8 (critique) are non-negotiable. Full guidance in references/plan-and-critique.md.

Tool mapping — OD-native ↔ OpenCode + our MCP

| OD upstream tool | What it does | OpenCode equivalent | Our MCP equivalent | |---|---|---|---| | TodoWrite | Live planning UI | OpenCode's todowrite tool | — | | Read | Read filesystem | OpenCode's read tool | — | | Write | Create file | OpenCode's write tool | — | | Edit | Modify file | OpenCode's edit tool | — | | Bash | Shell exec | OpenCode's bash (prefix rtk for read/git) | — | | WebFetch | Fetch URL | OpenCode's webfetch | — | | Glob / Grep | File / content search | OpenCode's glob / grep | — | | prompt_formatter_compose_brief | Format Turn 3 prompt | — | od_compose_brief | | live_artifacts_create | Create artifact | — | od_generate_design → od_save_artifact { identifier, title, html } (global store, NOT project-scoped) | | live_artifacts_update | Update artifact | — | od_save_artifact (same identifier → new timestamped dir) | | live_artifacts_list | List artifacts | — | od_get_project (note: returns project's files, NOT global artifacts saved via od_save_artifact) | | — | Save file inside project | — | od_save_project_file { projectId, name, content } (project-scoped; appears in od_get_project.files[]) | | connectors_list / connectors_execute | OAuth data extraction | NOT AVAILABLE — ask user for data manually | — |

Multi-page consistency (the new hot path)

After issue #37 (PR #40) shipped, od_generate_design accepts an optional projectId. When provided, it auto-fetches the project's stored customInstructions and merges them into the system prompt. Pair this with the playbook:

1. Turn 3, step 4: od_create_project { id: "<short-slug>", name, customInstructions: <brand spec from step 2> } → returns projectId (the id you supplied)
2. Turn 3, step 5 (each page): od_generate_design { projectId, prompt: "...page brief..." } — brand auto-inherited
3. od_generate_design accepts optional maxTokens (default 64000) — increase for very long pages, decrease for short snippets.
4. Result: every page in the project shares the same design language without re-pasting the brand spec

See references/workflow-examples.md for a fully-worked multi-page transcript.

Note: customInstructions is stashed in metadata.customInstructions on create/update and read from there first on generate (daemon compat, #43). This is transparent to callers.

Anti-AI-slop checklist (concise; full in references)

Transcribed from upstream discovery.ts:221-232 (Apache 2.0).

Audit before emitting any artifact. Any ❌ found → fix before od_save_artifact.

• ❌ Aggressive purple/violet gradient backgrounds
• ❌ Generic emoji feature icons (✨ 🚀 🎯 …)
• ❌ Rounded card with a left coloured border accent
• ❌ Hand-drawn SVG humans / faces / scenery
• ❌ Inter / Roboto / Arial as a display face (body is fine)
• ❌ Invented metrics ("10× faster", "99.9% uptime") without a source
• ❌ Filler copy — "Feature One / Feature Two", lorem ipsum
• ❌ Warm beige / cream / peach / pink / orange-brown page backgrounds (unless brand or selected direction requires)
• ❌ Product artifacts that expose designer settings, viewport selectors, "demo controls"

When you don't have a real value, leave a short honest placeholder (—, a grey block, a labelled stub). An honest placeholder beats a fake stat. Full slop checklist + the 8 other design philosophy principles in references/design-philosophy.md.

Quick start

Invoking from a parent OpenCode session. When the parent LLM detects this skill's trigger, it has two paths:

Option A — Inline execution (single-LLM, multi-turn chat):

• Parent LLM acts as the agent itself; follows this skill's rules turn-by-turn
• Best for short workflows or when the parent already has all needed context

Option B — Subagent delegation (recommended for full quality flows):

task(
  subagent_type="deep",
  load_skills=["od-workflow", "open-design-mcp"],
  prompt="<user's original design brief>",
  run_in_background=false,
)

• Spawn a fresh subagent loaded with both skills
• Subagent follows the playbook end-to-end; returns the final artifact summary
• Best for complete designs (multi-page, brand extraction, multiple iterations)

References (load on demand)

• references/discovery-form.md — Turn-1 form schema (verbatim), authoring rules, conversational fallback
• references/brand-extraction.md — Branch A 5-step extraction, brand-spec.md template
• references/direction-library.md — 5 directions with OKLch palettes + type stacks + posture rules (use when no brand provided)
• references/plan-and-critique.md — TodoWrite plan template, P0/P1/P2 checklist, 5-dimensional critique framework
• references/design-philosophy.md — Full 9-principle philosophy (A-I): persona, seed templates, anti-slop, variations, junior-pass, color/type, slides/prototypes, cross-platform, restraint
• references/workflow-examples.md — Two end-to-end transcripts (Branch A with brand URL, Branch B picking a direction)
• ATTRIBUTION.md — Apache 2.0 attribution, pinned upstream commit, transcribed-blocks table

Related skills

• open-design-mcp — the tool-reference skill. Catalog of 10 tools, env-var setup, error diagnosis, individual workflows (list / get / create / update / delete / compose-brief / generate / lint / save-artifact / save-project-file). Load this together with od-workflow for the full picture.

Related documentation

• Repo README.md — human-facing tool list + installation
• docs/architecture/generate-design-flow.md — deep technical reference for od_generate_design internals
• Upstream Open Design: https://github.com/nexu-io/open-design