Oh My Design

AI that designs like a human. OMD turns a design request into questions, evidence, alternatives,
real material, and rendered tests. The model chooses useful methods, then revises, retains, or
reframes its choices according to what it observes.

한국어

Built with OMD — in one shot

The landing page was generated by OMD itself from a single one-shot prompt — the visual output was not hand-tuned. View it at 3x-haust.github.io/oh-my-design.

What it is

Here, “design like a human” means accountable judgment, not a signature look. The goal is a repeatable process; the result can be quiet, expressive, conventional, or strange. What stays constant is the chain of decisions behind it.

The design practice contract makes this concrete inside each
selected method. Behavioral checks remain distinct from claims about human-level quality.
Local research and development notes under /docs/ are not tracked or published with the repository.

Concept exploration follows the content: a page can revolve around one strong idea, and alternatives
can share a brand palette. Visual drafts help choose a direction even when the delivered page is
entirely HTML and CSS. OMD compares feasible directions for their visible design and task fit;
passing a build or fidelity check alone does not establish visual quality.

Oh My Design (OMD) keeps a coding agent from jumping straight from a request to polished UI. It asks what problem is being solved, records evidence, separates writing from layout, compares anonymous structures, and critiques the rendered output without exposing the reviewer to the builder’s rationale.

The durable loop is adaptive rather than a mandatory stage checklist:

outcome + facts + risk → selected methods and reasoned skips → one production build
                       → real-surface interaction and visual evidence → causal repair or reframe

Task-critical product work can select a task-flow benchmark, semantic entry-surface contract, and
source-bound browser plan. Marketing work can select a different evidence, copy, composition, and
motion path. OMD preserves the user's model choice in both cases. It derives evaluator selectors
from current task records instead of accepting a caller-authored answer key, and it does not invent
a product capability merely to make an under-specified greenfield concept look distinctive.

OMD runs inside Codex, Claude Code, and hosts that implement the public Pi extension API. It ships six user-facing skills, nine internal pipeline agents, a local omd CLI, design theory and recipe packs, and a durable project record under .omd/.

Requirements

• Node.js 22.19 or newer (the CLI runs the TypeScript entrypoints directly)
• Claude Code, Codex, or a Pi-compatible host
• A browser provider: browser-rs v0.1.10 is preferred on its two supported platforms; Playwright + Chromium remains the required fallback for rendering, probing, and typography proofs (see below)

Install

npm — global CLI (recommended)

npm install -g @3xhaust/oh-my-design
oh-my-design install    # copy skills + agents into every detected host and patch its config
oh-my-design doctor     # verify the host install
omd doctor              # verify the runtime, Chromium, project write access, and the theory pack

oh-my-design install --host claude|codex scopes install, doctor, and uninstall to one host. uninstall reverses exactly what install did and never touches your .omd/ directory. Host installation also attempts browser-rs afterward and reports present, installed, unsupported, or failed; a browser-rs failure does not roll back an otherwise healthy OMD/Playwright host installation.

Install the scoped package @3xhaust/oh-my-design. The unscoped oh-my-design on npm is an unrelated project.

Pi-compatible hosts — extension package

OMD is a standard Pi package. Pi and API-compatible forks such as Senpi load the same extension
and canonical skills; OMD does not probe or launch a Senpi executable.

pi install npm:@3xhaust/oh-my-design

For a compatible fork, use that host's package-install command with the same npm package. The
extension registers /omd for a project doctor check and the structured omd_cli tool for the
existing OMD CLI. Compatibility requires the public Pi extension/package API; fork-only APIs are
not used.

Pi's omd_cli does not need an external activation file. First run
omd route validate --input .omd/.cache/route-input.json --json, repair the named input errors,
then publish with route classify. An input validation error is not missing host authentication.

Three-layer enforcement connects declaration → stage/owner procedure → automatic refusal.
The coordinator inspects each brief, delivers its contracts, then runs omd brief <stage> --check --json.
Plain brief inspection is not entry permission. Production entry uses the full production readiness
validator; routed recipe add checks all targets before writing, even outside Pi.
Pi's public tool_call / message_end hooks ensure native write/edit application mutations
and arbitrary bash wait for current pre-production inputs; research inputs and directly owned
design documents remain writable. The completion hook withholds an unverified final success claim.
OMD commands are queued per project to prevent sibling calls from competing for the mutation lock.
During a source-writing turn, repairable terminal failures keep triggering repair/recheck follow-ups
while the named work pointer or authored evidence changes. Two consecutive unchanged failure states
stop the loop; authority failures and user aborts do not retry. Message replacement semantics are verified against Pi
0.85.1; forks must support that public event behavior, not merely expose an on function.
An explicit full-build request with the packaged skill also continues a checked selected stage on
an existing route after a failed publisher; research-only or stop-at-stage requests do not.
Run /omd after /reload; hook-less compatible hosts explicitly report that only CLI checks exist.
Hooks are workflow gates, not an OS sandbox or proof of design quality. External processes/custom
mutation tools are outside this hook boundary, and streamed draft text may precede final validation.
Independent reviewer authorization is still required by implementation final evidence; Pi does not
manufacture it. After upgrading, revalidate/reclassify the original approved route with the current
build if old build/skill authority is stale. stage status.completed means artifact presence only.

Reference research is saved separately: .omd/refs/domain/research.json for similar-service screens,
features and flows, and .omd/refs/design/research.json for composition, type, density and component
craft. omd ref discover-plan --json suggests screen galleries such as Mobbin/Page Flows/UI Bowl/Pinterest for product
UI and website galleries such as Siteinspire/Pinterest for marketing. Verify free access per entry;
on blocked/login/paid access, use another public source without purchases, trials or MCP installation.
Free viewing does not grant reuse rights. Record the inspected screen, discovery entry and concrete
quality reason, not just a prestigious gallery name. Visit gallery items with omd ref navigate <item-url> --lane design --json; their captures stay under .omd/discovery/design/. Retain the
observed original or capture the loaded UI image with ref add <item-url> --lane design --selector <img-css>, not the wrapper chrome; cropping is optional. Use omd schema reference-research --json,
omd ref research-set --input <input.json> and omd ref research-check --json to publish/check both
files and their aggregate consistency receipt. Capture PNGs and metadata directly into their own
folders with ref add --lane domain|design or lane on each add-batch entry. Inspect them with
ref list --lane domain|design --json; domain captures do not silently enter the visual board.
Current v7 research binds source and gallery-entry PNGs to native capture JSON, keeps domain and
design lanes separate, and records source-specific market coverage when a market is explicit or a
Korean-language user brief starts Korean-first reference research. That default never dictates a
country aesthetic. Korean welfare discovery now starts with actual service-name searches on the
public Daum web endpoint; Korean-language .com products can qualify, while English foreign
government domain captures are refused until current local-domain research validates the local
coverage and any global fallback. Locally authored capture files or --from-user alone do not
unlock that fallback. Selector-scoped captures check the full page's visible-language balance.
A homepage is not an inspected
entry, and a different original source must appear in the gallery's observed outbound links.
Historical v5 remains readable with search-only requirements; v6 retains its search-or-direct-root
contract. Reuse valid captured evidence only when current validators permit, then publish through v7
without relabelling historical bytes.
Domain/design hosts, final redirects and PNG evidence must be independent. Non-user discovery must
be a supported public gallery item, not a service page labelled as a gallery. Public Pinterest,
Dribbble and Behance items do not require UI Bowl's paid MCP. Free viewing is checked per item.
Design sources declare visual-direction or component-support with observed composition, type,
density, imagery, transfer and exclusions. Current v7 needs at least two independent visual-direction
service families from distinct inspected gallery items with different PNG bytes, and both directions
must participate in the current board. Tracking URL variants, renamed captures, and unused screenshots
do not count. Every board candidate uses visual-direction evidence; support-only documentation cannot
complete the lane. Inspect previews in .omd/refs/design/README.md.
These are provenance/role checks, not a machine certification of beauty.

Current v7 requires native acquisition evidence, not query prose. omd ref search --input <json> accepts
{lane, query, url, queryParam} and records a fresh-browser GET, actual links/capture or failure.
Put its returned receipt in the lane's searches. Every query must match an execution and retained
non-user sources/entries must occur in observed links and have separate native visit captures.
Failed attempts can accompany a usable free alternative. HTTP 200 alone is not search quality.
The executor accepts public Google/Bing/DuckDuckGo search pages with queryParam: "q"; use task/pattern
and gallery site: queries. Arbitrary service pages with invented query parameters are rejected.
When search is blocked, v6/v7 also allow signed direct-public list discovery through omd ref navigate.
New search-v2 and direct-entry-v3 records are project-signed and tamper-evident, but they are not
provider-attested truth and do not certify quality, market fit or authority.
For explicit-market local coverage, a signed search result's visible link text must name the market
and relevant service/product scope. A localized query by itself does not make a source local.
Both that provenance and the retained source observation must be no more than seven days old.
Direct-public local coverage applies the same rule to the selected link's visible label; a market
heading elsewhere on the directory cannot qualify an unrelated service. Every declared attempt and
chosen retained capture is time-limited. Each global fallback source also binds to the exact signed
search/direct receipt whose visible label reached it.

After research, omd ref apply-plan --json creates an incomplete input draft for every current
domain-brief surface. Inspect the actual images, fill the draft's input, and publish it using
omd ref apply-set --input <application.json>; omd ref apply-check --json verifies it. Each screen
keeps separate domain/design reference IDs, direct/partial/brief-derived coverage, gaps, what to
apply, what not to transfer, why, and future rendered checks. .omd/reference-application.md shows
the plan; briefs and selected handoffs deliver only the source-free decision projection. Research
or scope changes invalidate it. Current v4 captures can be retained without recapture, but no
decisions are invented for them. This adapts Design Flow Harness's screen-linked research approach,
not its fixed Figma pipeline. A plan does not prove rendered use, quality, or user approval.

Source sealing now binds the application plan. After authenticated final evidence, run
omd ref apply-review-plan --json, inspect each criterion on current desktop/mobile captures,
then apply-review-set --input <json> and apply-review-check --json. Missing, unresolved or stale
judgments block terminal completion; changes require resealing, recapture and re-review.
Review reasons are agent-authored, not human approval. omd schema reference-flow-input and
omd benchmark record --input <flow.json> execute public navigation/disclosure steps in one fresh
context and publish signed, project-bound receipts. Only bound completed flows can report
liveFlowVerified: true; artifact-only history remains unverified and cannot clear a selected product
benchmark. Login, payment, submission and destructive controls remain explicit exclusions.

Similarity discovery may keep intermediate native captures in each lane's optional navigation
array (url, PNG evidence, JSON capture). Only observed links rooted in a successful search
extend the chain. Screen application v2 binds each destination route/state before production;
final review cannot substitute a home capture for a different surface. First-render checking uses
--page <local-build.html> plus the observed projection, saves a native capture, and invalidates
its report when the hypothesis/source/build changes. Comparison is explicitly task-applicable and
advisories do not block completion by themselves.

For an existing service, omd init --json inventories static CSS variables/declarations and $value
token JSON into .omd/existing-design-system.json and .md. Scopes, aliases and source locations/hashes
remain intact. It never changes app files or approved .omd/tokens.json. Future briefs reuse the
inventory; omd init --check detects stale inputs and omd init --refresh refreshes observations.
Keep authored decisions in .omd/design-system-decisions.md, preserved across refreshes. Runtime styles,
Tailwind configuration and component variants are not silently inferred from static files.
For runtime values use omd schema runtime-design-inventory-input then omd init --input <input.json>:
named component selectors and optional SPA states are rendered from a bundled local build. Computed
CSS-in-JS/utility styles and custom properties are saved in .omd/runtime-design-system.json and .md.
init --check detects stale source/build/captures; init --refresh repeats the recorded scope. Future
briefs reuse current observations, never treating them as approved semantic tokens or unvisited variants.

Implementation completion uses omd schema slop-scope → omd slop checkpoint --input <scope.json> →
inspect the native captures → omd slop review-set --input <review.json>. Confirmed issues require
owner repair, rebuild, same-scope recapture/rescan, and an explicit after-render resolution.
omd slop review-check, CLI finalization and terminal preflight reject missing, stale or unresolved
loops. Candidates/warnings remain advisory; reasoned dismissals are valid and a clean first review
needs no invented repair. Capture currently supports local HTML build entries, not arbitrary localhost
ports. Optional per-view state: {name,startRoute,route,actions,assertions} covers SPA routes, modals
and error states; the native executor preserves state and blocks external networking/API writes.
Final linked browser states require matching route/state/viewport scope and exact viewport pixels
from the authenticated final capture; replay the same deterministic data and settled state. Native
checkpoint/inventory signatures reject edited documents masquerading as observations. This does not replace
functional coverage, independent quality review, or user approval.
Legacy files are preserved; renamed identical images still cannot satisfy both lanes.

For design before implementation, use omd schema design-route-input with deliveryMode: design-only.
Output stays under .omd/**; research, design, review, and handoff proceed without application source.
Bind the documents using omd schema design-handoff, then run
omd completion design-check --input .omd/design-handoff.json --json.
This checks document integrity, reference evidence, and write scope. It does not attest application
behavior or independent review authorship.

Claude Code — plugin marketplace

/plugin marketplace add 3x-haust/oh-my-design
/plugin install oh-my-design@omd

Then open a session and run /ultradesign.

From source (contributors)

git clone https://github.com/3x-haust/oh-my-design
cd oh-my-design
npm install
node bin/omd-install.ts install    # copy skills + agents into detected hosts
node bin/omd.ts doctor

# Test the source extension in Pi without installing it globally.
pi -e ./extensions/omd.ts

Browser provider and Chromium (after global installation)

After globally installing @3xhaust/oh-my-design, OMD prefers the browser-rs MCP provider for interactive reference research, user-directed region captures, and visual QA. It is a deliberately narrow v0.1.10 integration, not a claim of universal browser compatibility:

The managed binary, when installed, is $HOME/.local/share/oh-my-design/browser-rs/v0.1.10/browser-rs with a verified receipt.json. OMD verifies the exact checksum before publishing it. Resolution is OMD_BROWSER_RS_BIN, then browser-rs on PATH, then that receipt-owned target. OMD never overwrites a foreign override/PATH binary or an unreceipted/tampered managed-target file, and oh-my-design browser uninstall removes only matching OMD-owned receipt-and-digest bytes.

# Explicit provider lifecycle. `doctor` exits 1 when the selected provider is not healthy.
oh-my-design browser install
oh-my-design browser doctor --json

# After global package installation, provide your own equivalent local HTML fixture.
oh-my-design browser smoke --fixture /absolute/path/to/local-probe.html --out /tmp/omd-browser-rs-smoke.png

# Preserves foreign, unreceipted, or tampered bytes rather than deleting them.
oh-my-design browser uninstall

From a source checkout, use the proven TypeScript entrypoint instead of assuming a global bin:

node bin/omd-install.ts browser install
node bin/omd-install.ts browser doctor --json
node bin/omd-install.ts browser smoke --fixture test/fixtures/probe.html --out /tmp/omd-browser-rs-smoke.png
node bin/omd-install.ts browser uninstall

On a supported platform, missing, unowned, or bad browser-rs is unhealthy; first repair the intended binary/ownership (or intentionally set OMD_BROWSER_RS_BIN), then rerun browser doctor. On an unsupported platform, provider health is good only when the Playwright module and Chromium fallback are both available. Existing omd render and omd probe are the deterministic Playwright fallback after browser-rs initialization or capability failure.

The installer does not install Chromium. If omd doctor reports Playwright unavailable or its Chromium executable missing, install what the report names, then re-check:

npm install -g playwright
npx playwright install chromium
node bin/omd.ts doctor

Chat-first LEGO reference assembly

OMD treats a reference as a set of traceable bricks selected for the approved brief, not as a whole-site style to copy. The canonical sequence is:

brief blocks → fragment inventory → brick analysis → candidate assemblies
→ selected assembly → clean-room composite → production usage ledger → final provenance report

The conversation is the interface. Codex/Claude shows the candidate table and the final Korean/English provenance table directly in chat. There is no omd-board executable, DESIGN UI, HTML board, or PNG board. The reference board is an internal, validated .omd/reference-board.json record; the package exposes only the public omd and oh-my-design bins.

Behind the conversation, an agent can capture a component, validate the evidence, render the chat-ready candidates, and bind the user’s chat choice:

# Internal agent operations; the person reviews the resulting Markdown in chat.
omd ref add <url-or-local-page> --as <component> --selector '<css>' --blueprint --shot
omd ref import-image ./local-fragment-input.json
omd ref board --input candidate-assemblies.json
# Market-grounded routes also author and check the source-free slot-to-decision binding.
omd ref locale-bind --input reference-locale-binding.json
omd ref locale-bind-check
omd ref check
omd ref candidates
omd ref select <candidate-id>
omd ref check

omd ref candidates emits a Korean-first Markdown table with source site/page, captured UI or image part, proposed route/component, take, avoid, and adaptation. It does not open a board. The selection is hash-bound to both validated raw evidence and its sanitized reference assembly.

Captures, clean-room composition, and final traceability

Short standalone component examples need not be mistaken for empty pages: OMD checks the requested HTML element's rendered size, visibility styles, and text. This is not a visual-quality verdict. HTTP 403, server errors, and challenge pages remain rejected.

Desktop and mobile views of the same component stay together without inflating reference diversity. State-preserving capture can observe existing focus or an explicitly opened disclosure; unmeasured interaction and motion remain unknown. See the capture protocol.

Motion reference capture can observe a loaded component while background requests remain open. Its returned measurements still need visual inspection; they are not a design-quality or accessibility certificate.

A component brick is a selector-scoped blueprint plus a local PNG. For Pinterest-like galleries and similar sources, browser-rs performs the user-directed region capture and omd ref import-image imports that local PNG. The input records absolute HTTP(S) sourcePage, optional sourceImage, human-readable captureRegion, optional cropBox, licenseStatus (allowed, restricted, or unknown), rights notes, visual role/principles, and canonical provenance time. OMD does not scrape, hotlink, download remote source images, or ship their pixels.

The composer receives only the sanitized selected assembly: transferable structure/principles/geometry, never a source URL, source selector, provenance, screenshot, local source image, or raw pixels. The assembly intentionally retains its target targetSelector so implementation can map a selected part to its destination. .omd/reference-composite-lineage.json records either a hash-bound generated clean-room composite or an unavailable reason. When host image generation is available, independent concept drafts may be generated concurrently and compared, with the count chosen for the unresolved design question; no image-provider or API-key layer is added. When unavailable, use a CSS/SVG/evidence fallback. Existing motion, prefers-reduced-motion, and WebGL/3D gates are unchanged.

During implementation, each selected source part receives a used, rejected, or anti-reference row in .omd/reference-usage.json. .omd/reference-report.md and the final chat response contain Korean and English tables with: status; source site/page; exact captured UI/image region; shipped route/component/selector; borrowed properties; explicitly non-borrowed properties; transformation; and production evidence path, selector, and verification note.

See the reference assembly protocol for capture, evidence, source-isolation, and transfer contracts.

Early concept studies on Codex

When a design direction is still open, Codex running through omd-codex can make provisional HTML studies from supplied content before the full composition is approved. Desktop and mobile renders let you compare how different arrangements communicate that content. These optional studies are separate from production: they do not replace reference work, copy and typography checks, or final review. This is an HTML-study capability, not an image-generation service or a guarantee of design quality. See the study protocol for the supported host workflow.

Designed around your material

Ordinary /ultradesign use needs no style vocabulary. When real first-party content has a stable
shape, OMD may adapt composition to its lengths, counts, aspect ratios, or semantic outliers. The
result includes a read-only Fit Receipt showing what stayed intact and where the desktop and mobile
evidence lives. OMD stores hashes, project-relative paths, and bounded measurements, not raw content,
and it never infers taste from silence. The related CLI commands are an expert and debugging surface,
not a new step for everyday use.

Designed for the language and market you actually mean

OMD does not treat localization as sentence translation, and it does not map a language code to a
country theme. It keeps the conversation language separate from the surface locale, explicit market,
audience and task, domain, surface type, and brand invariants. ja-JP can establish Japanese script
mechanics; it cannot by itself authorize a Japanese market aesthetic. Bare zh does not silently
become mainland China, and zh-CN and zh-TW remain separate contexts.

For ordinary /ultradesign use, state the surface language and intended market/audience. If market
or audience authority is missing, OMD asks one focused question and stops that research route if it
remains unresolved. The locale context's marketAuthorityClaimId must name a confirmed
evidenceClaims.userFacts claim whose user evidence actually names that market. A mechanics-only route checks real target-language copy and type mechanics but
makes no cultural-fit claim. A market-grounded route collects current
standards, a global equivalent or exact unavailability, native first-party category evidence, and a
counterexample for the named decisions. It preserves only supported/shared mechanisms, routes conflict
as contested, and turns missing evidence into unknown rather than a visual rule.
The comparison lanes must serve the same named task or category; a generic homepage from the same
institution is not an equivalent. Recorded unavailability limits confidence and never votes for
convergence.

Expert/debugging surface. This is not a standalone quickstart: run only the commands selected by the
current route. The host launcher supplies OMD_ACTIVATION_PATH; each omd schema command prints the
input skeleton, and source capture repeats once for each declared evidence source.

omd schema locale-design-context
omd locale plan --input .omd/locale-design-context.json --json
omd route classify --input .omd/.cache/route-input.json \
  --locale-context .omd/locale-design-context.json \
  --activation "$OMD_ACTIVATION_PATH"
omd locale source-capture --url https://example.org/current-source \
  --activation "$OMD_ACTIVATION_PATH" --json
omd locale profile --publish --input cultural-profile.json \
  --activation "$OMD_ACTIVATION_PATH" --json
omd locale profile-check --activation "$OMD_ACTIVATION_PATH" --json
omd schema reference-locale-binding
omd ref locale-bind --input reference-locale-binding.json --json
omd ref locale-bind-check --json

The profile and sanitized projection are content-addressed and bound to current source bytes,
target-language type proof, route context, and brand invariants. Production roles receive the
source-free projection, never source URLs or a country-style prompt. Agent review can report
evidence-grounded adaptation only. OMD does not claim that a result is culturally native or preferred
without genuine blind ratings from the named target audience, collected independently from actual members.

When a market-grounded route also uses a reference board, the locale binding closes the last mile:
each local reference slot must name the exact supported or shared profile decision it implements.
Positive transfer requires a captured native-category component (and may also use a task-equivalent
global source); anti-reference transfer requires a counterexample cited by the profile. contested and unknown
decisions cannot silently become design rules. Composer, Hand, and Eye see only the source-free
slot-to-decision projection, while source-owner-only IDs and capture hashes remain withheld from those
downstream roles in the evidence record.

The human design loop

omd-ultradesign coordinates the applicable work below. This is the complete capability map, not a
universal sequence: the adaptive route records selected stages and methods, dependency order, and a
reason for every omitted optional item.

1. Preflight — pin the project directory, run omd doctor, inspect the repository, and route Figma briefs to omd-figma.
2. Frame — interrogate the brief and record the problem, reframe hypothesis, primary task, frequent action, and costliest error with cited evidence.
3. Concept — choose a generator, visual register, typography direction, and the intended memorable moment.
4. Research — collect measured references across the domain, competitors, audience language, components, typography, and relevant motion.
5. Write copy — a dedicated writer creates a fact-traceable copy deck before layout begins.
6. Review copy blind — a fresh reviewer sees the brief, copy, fact ledger, and voice evidence, but no render, code, layout, rationale, or authorship.
7. Prove typography blind — a typesetter renders layout-neutral actual-copy specimens at 1280×900 and 390×844; a fresh eye reviews them without page structure or rationale, then the typesetter revises and rerenders.
8. Compose deliberately — a fresh composer defines the experience spine, one dominant focal anchor, mass/rhythm, a lawful mechanism carrier or explicit alternate, responsive recomposition, and candidate axes. omd composition --check verifies input freshness.
9. Diverge structurally — isolated agents receive the same composition contract. Normally they render fixed desktop/mobile plus supplemental full-page continuity proofs; when an exact routed candidate scene uses the host-evidence-only contract, the sketch implements that one preproduction scene and the host independently captures every proof and receipt.
10. Choose blind — a fresh selector scores eight frozen 0–4 dimensions, rejects contract violations or any dimension below 2, and never equates a form above the fold with CTA reach.
11. Build once — one selected structure becomes the production implementation. The builder does not generate another candidate set.
12. Reflect while building — the builder records a semantic checkpoint, re-proves type in the selected desktop/mobile containers, then records the visual checkpoint before optional motion.
13. See the result — desktop and mobile renders, squint views, applicable filmstrips, deterministic checks, and declared local probes supply the review evidence.
14. Triage source candidates — after production source exists, a read-only scan proposes narrow candidates. The coordinator resolves each through rendered context; candidate presence alone is not a failure.
15. Critique, repair, and reframe — a squint-only glance reports hierarchy first; a separate sharp reviewer judges craft and sanitized candidates, then repairs are rendered, checked, and rescanned.
16. Ship — project tests, build checks, applicable design gates, and unresolved findings are reported with their evidence.

Figma files and explicit visual targets already supply structural decisions, so the loop may skip structural divergence in those routes — but it records why.

Skills

Six user-facing skills. Canonical names use the omd- prefix; Codex shows them as (omd) <skill>, and the Claude marketplace flavor references them as oh-my-design:<skill>.

Internal pipeline agents

Nine agents are implementation details of the loop, not public commands. They do not pin a concrete model. By default, each uses the user's configured model and its source-owned effort tier.

For one Codex host invocation, the user can route an official role to a model and a
low, medium, or high effort without changing package defaults:

omd-codex exec -C /path/to/project \
  --model gpt-6-astra -c 'model_reasoning_effort="medium"' \
  --omd-role-model omd-eye=gpt-5.6-sol \
  --omd-role-effort omd-eye=high \
  --omd-role-model omd-hand=gpt-5.6-sol \
  --omd-role-effort omd-hand=medium \
  '$omd-ultradesign continue the current route'

Repeat either host-only option for each mapped role. The launcher removes these private options
before starting the coordinator, binds them to that run, and lets only the broker apply them to
the mapped child. Unmapped roles still omit a model argument and keep their agent-profile effort.
omd-codex role run and omd-codex owner run do not accept these options.

Claude Code can enforce declared denied tools in agent metadata. Codex agent files have no equivalent tool-restriction field, so read-only limits there are prompt contracts rather than a hard sandbox. OMD does not describe those contracts as filesystem isolation.

Evidence boundaries and artifacts

Human approval checkpoints are separate from craft checkpoints. Projects default to checkpoint: none; concept, structure, or both can be enabled in .omd/config.json.

Stack routing

Every builder follows the same precedence:

explicit user request
  > existing repository stack and toolchain
  > React + Vite + TypeScript for a truly blank greenfield

Existing vanilla HTML is an existing stack. An unrecognized package or toolchain is investigated and preserved, not treated as an empty repository. Plain HTML for a new greenfield project is used only when the user explicitly asks for it. Greenfield scaffold dependencies are allowed; existing projects should not receive unnecessary ones.

Verification stack

OMD combines deterministic checks with rendered review.

Slop findings are a quality floor and warnings; they do not prove a design was generated by AI. A written overrule records intent but does not suppress a finding or change command status. Rendered critique remains necessary — a rule engine cannot safely judge optical balance, composition rhythm, typography craft, or whether the memorable moment belongs to the concept.

Interaction applicability

The copy deck declares exactly one interaction scope.

Loading, empty, error, success, disabled, offline, and recovery states are designed only when the surface can reach them — the harness does not add fake states to satisfy a checklist. Probe plans use declared click, fill, and keypress steps with explicit expectations, are limited to local files and localhost/loopback URLs, and reject authenticated, remote, destructive, or undeclared actions. OMD never discovers controls and clicks them automatically.

Project state

Durable, reviewable records live directly under .omd/:

• frame.md, copy-deck.md, type-proof.md, composition.md, source-seal.json, design.md, decisions.md
• attribution.md, motion-spec.md, craft.jsonl, config.json
• refs/*.json, reference-board.json, reference-locale-binding.json, reference-locale-binding-evidence.json, reference-selection.json, reference-composite-lineage.json, reference-usage.json, reference-report.md, declared probes/*.json, taste/preferences.jsonl, and history.jsonl

Generated IR, renders, filmstrips, sketch candidates, probe results, and scratch output live under .omd/.cache/; deleting the cache should not erase design intent. oh-my-design uninstall removes installed OMD files and config changes while preserving the project’s .omd/ directory.

CLI reference

A compact map of node bin/omd.ts --help:

omd ir <page> [-o file]
omd render <page> -o shot.png [--viewport WxH] [--full-page] [--squint] [--filmstrip]
omd probe <page> [--plan path] [--json] [--out path]
omd check [<page>|--ir file] [--json] [--category slop] [--no-log]
omd check --site <dir>
omd check <page1> <page2> ...
omd slop scan [root] [--json]
omd coach
omd composition --check [--json]
omd source --seal [root]  |  omd source --check [root] [--json]

omd frame show
omd frame set --problem P --reframe R --why EVIDENCE [--task T --frequent-action A --costliest-error E]
omd frame reframe --to "..." --because "..."
omd frame generator --set "metaphor"
omd choose c1 c2 --chose c2 --why "..."
omd decision "what" --why "why"
omd taste record "subject" --kind selection|praise|rejection|overrule --evidence "verbatim" --from-user
omd taste profile [--all]
omd config set checkpoint none|concept|structure|both  |  omd config show
omd craft checkpoint semantic|visual --render path --observed "..." --decision revise|retain|reframe --criterion "..." --reason "..." [--changed "..."]
omd craft status [--json]

omd ref add <url|file> --as <component> [--selector "css"] [--image] [--blueprint]
omd ref list  |  omd ref distance <page> [--selected [--gate]] [--json]
omd ref principles <source> --as <component> --add "..."
omd ref show <source> --as <component>
omd ref board --input candidate-assemblies.json
omd ref locale-bind --input reference-locale-binding.json  |  omd ref locale-bind-check [--json]
omd ref check [manifest] [--json]
omd ref import-image <input.json> [--json]
omd ref candidates [manifest]                 # chat-ready Korean-first Markdown; no board UI
omd ref select <candidate-id> [--json]

omd design  |  omd design --check
omd copy --check [--json]
omd pack dir | list | <relpath>
omd doctor

omd figma pull <file-url>  |  omd figma system  |  omd figma diff <frame-id> <page-or-url>
omd target set <image-path-or-url> --as <name>  |  omd target list  |  omd target diff <page> [--target <name>] [--viewport WxH] [--threshold N] [--json]

Architecture

Prompt source of truth:

• src/agents/*.agent.yaml
• src/skills/omd-*/SKILL.md

Generated outputs — do not edit directly; npm run build regenerates them for direct hosts and plugin packaging:

• agents/, skills/, dist/

Edited directly: core/, bin/, adapters/, test/, evals/, scripts/, README.md, README.ko.md, and the theory and recipe packs under core/.

Testing

Tests are classified as unit, integration, browser, native, or packaging. npm test builds stale generated output when needed and runs every tier with safe concurrency; use npm run test:unit or another test:<tier> command for focused work. Coverage uses the deterministic unit and integration tiers.

npm test
npm run test:coverage
npm run typecheck
npm run build

Contributing

See CONTRIBUTING.md for setup, test classification, three-layer enforcement, generated artifacts, and the branch-to-PR workflow. New linter rules must remain narrow, include positive and negative tests, and always use warning severity.

Limits and trust

• The prompts define a disciplined workflow; they do not guarantee strong design without real project evidence, usable copy, rendered inspection, and project-specific validation.
• Probes are for local, non-authenticated, non-destructive paths — not a general browser automation layer.
• Reference distance, lint, and image diff are measurements. They inform judgment rather than replace it.
• Plugin/marketplace manifests are shipped artifacts; the from-source direct installer is the path covered by install-to-doctor regression tests.

Licensed under the MIT License.