oh-my-design
AGENTS.md588 starsChanged 34 days agoMITView on GitHub
This is the agent-instruction shim for OpenAI Codex / generic AGENTS.md-aware CLIs working inside this repository. oh-my-design itself uses Claude Code skills + subagents for its design harness. This file is the parity layer for Codex users. User-facing entry: /omd-harness <task> in Claude Code or Codex CLI. The harness runs entirely inside the host CLI session — no external API keys, no separate process. The skill at .agents/skills/omd-harness/ (Codex) or .claude/skills/omd-harness/ (Claude Code) handles bootstrapping and orchestration handoff. Examples: -…
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository89 other files it gives its agents.
- web/AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- web/CLAUDE.mdCLAUDE.md
- ego-browserSkill
- google-analyticsSkill
- omd:add-referenceSkill
- omd:batch-launchSkill
- omd-component-harvestSkill
- omd:designSkill
- omd-lab-01-designmd-impactSkill
- omd:migrateSkill
- omdSkill
- omd-token-backfillSkill
- claude-designSkill
- hangulSkill
- omd:add-referenceSkill
- omd:aphroditeSkill
- omd:applySkill
- omd:asset-fetchSkill
- omd:autopilotSkill
- omd:batch-launchSkill
- omd:cjk-type-shaderSkill
- omd:codex-imageSkill
- omd-component-harvestSkill
- omd:designer-reviewSkill
- omd:experiment-gallerySkill
- omd:feelSkill
- omd:final-qaSkill
- omd:harnessSkill
- omd:humanizeSkill
- omd:initSkill
- omd:issueSkill
- omd:kr-writerSkill
- omd-lab-01-designmd-impactSkill
- omd-lab-02-design-harnessSkill
- omd:landingSkill
- omd:learnSkill
- omd:locale-adapterSkill
- omd:mediaSkill
- omd:migrateSkill
- omd:orchestratorSkill
- omd:reference-captureSkill
- omd:release-hygieneSkill
- omd:rememberSkill
- omd:restraintSkill
- omd:setupSkill
- omd:shader-heroSkill
- omd:showcaseSkill
- omdSkill
- omd:slop-auditSkill
- omd:syncSkill
- omd:tasteSkill
- omd-token-backfillSkill
- omd:updateSkill
- claude-designSkill
- hangulSkill
- omd-3d-heroSkill
- omd-aphroditeSkill
- omd-applySkill
- omd-asset-fetchSkill
- The first 60 shown.
The file
Show its rules and text
We split this AGENTS.md into the rules it gives an agent
15 rules. About 0 are common, 7 are distinctive, and 8 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈7
Distinctive · estimate
This author's own choices. Worth a look.
8
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 51
When this AGENTS.md is loaded and a fresh .omd/runs/run-<latest>/ exists:
- Very specific: line 53
Activate the orchestrator persona: Read .codex/agents/omd-master.toml and adopt that role.
- Very specific: line 78
All artifacts go inside the run dir: Never write outside it except for DESIGN.md (Phase 5, with user checkpoint approval) and …
- Very specific: line 94
Read project-root DESIGN.md in full at the start of the turn.
- Very specific: line 95
Read .omd/preferences.md pending entries — these override DESIGN.md until folded in.
- Very specific: line 97
If the user corrects your design choice, run omd remember "<one-sentence summary>" --context "<file>" before ending the turn.
- Distinctive: line 104
Use browser-harness only when explicitly selected for a capability that Computer Use cannot provide and after checking that its connection …
- Distinctive: line 106
Keep each cell's prompts, tabs, results, and downloads separate.
- Very specific: line 118
Before finishing catalog UI work, verify Home → brand row → /design-systems/<id> → #use (Copy DESIGN.md, Download), on /ko as well as /.
- Very specific: line 128
Never fabricate brand, principle, or persona facts.
- Distinctive: line 131
Never introduce a token absent from DESIGN.md without going through Phase 5 (system extension with checkpoint #2 approval).
- Distinctive: line 133
Never download from Pinterest.
- Distinctive: line 134
Never emit SUS / NPS / "satisfaction score" from synthetic personas.
- Distinctive: line 135
Never auto-skip user checkpoints.
- Distinctive: line 136
Never delete a run directory.
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
AGENTS.md — oh-my-design
This is the agent-instruction shim for OpenAI Codex / generic AGENTS.md-aware CLIs working inside this repository.
oh-my-design itself uses Claude Code skills + subagents for its design harness. This file is the parity layer for Codex users.
Repository quick map
src/— TypeScript source for theomdCLI (bin/oh-my-design.tsis the entrypoint).web/references/<id>/DESIGN.md— one real company's DESIGN.md per folder; the canonical source of truth for the reference catalog. It lives underweb/because the Vercel project root isweb/(the site build can only read files beneath it). The rootreferencessymlink,design-md/, andpackages/mcp/data/references/are all derived from here. Rule: editweb/references/only.skills/omd-*— Claude Code / Codex / OpenCode skill files (installed into target projects viaomd install-skills)..claude/agents/— Subagent definitions for the design harness (Claude Code)..codex/agents/— Mirror TOML definitions for the design harness (Codex).artifacts/— machine-generated working output. Mixed on purpose:reference-create/is committed run history, whilereference-evidence/(145MB of capture bundles) andreverify/are local-only and never committed (owner decision, 2026-09-16). Not disposable — they are the input to repairing verified references without a browser re-run.artifacts/local-store.manifest.jsonrecords per-file SHA-256s andnode scripts/local-store.mjs --verifychecks custody. Rules and backup location:artifacts/README.md.spec/design-md-core-v2.md— normative vendor-neutral DESIGN.md Core v2 contract.spec/omd-v0.1.md— legacy 15-section import format; dual-read only.research/harness-design/— Design harness research + integration design.skills/omd-lab-02-design-harness/— Lab #02 versioned harness experiments.scripts/ctx-prime.cjs— v1.6.0 deterministic codebase analyzer (stack, brand color, voice, surface inventory, audience hypothesis). Called byomd-harnessStep 2.5 to pre-fill master slots.
Build / test / lint
- Build:
npm run build(tsup →dist/) - Type-check:
npm run lint(tsc --noEmit) - Unit tests:
npm test(vitest) - The CLI runs via
node dist/bin/oh-my-design.js …after build.
Design harness mode
User-facing entry: /omd-harness <task> in Claude Code or Codex CLI.
The harness runs entirely inside the host CLI session — no external API keys, no separate process. The skill at .agents/skills/omd-harness/ (Codex) or .claude/skills/omd-harness/ (Claude Code) handles bootstrapping and orchestration handoff.
Entrypoint
/omd-harness <도메인 + 톤/스타일 + 핵심 화면>Examples:
/omd-harness 토스 스타일로 가족용 식단 공유 앱 메인 화면/omd-harness Linear-clone B2B SaaS dashboard — 6 widgets, dark first/omd-harness 결제 완료 화면 — 성공/실패/부분성공 3 states
For Lab #02 versioned runs, append --lab v1 (or v2, v3 …) inside the slash command.
The skill bootstraps the run dir inline, not through the CLI: the shell block at skills/omd-harness/SKILL.md:97 derives the slug, creates .omd/runs/<run-id>/ and its standard subdirs with mkdir -p, writes task.md, and appends to .omd/runs/INDEX.md. There is no omd harness command — the omd binary never had one. Always enter through /omd-harness.
Codex-specific harness flow
When this AGENTS.md is loaded and a fresh .omd/runs/run-<latest>/ exists:
- Activate the orchestrator persona. Read
.codex/agents/omd-master.tomland adopt that role. The full behavioral spec lives at.claude/agents/omd-master.md— follow it verbatim regardless of channel. - Run the 10 phases in order (see
.claude/agents/omd-master.mdfor full details):- Phase 1 — Discovery (5-8 questions, one batch)
- Phase 1.5 — Asset Brief (spawn omd-asset-curator)
- Phase 2 — UX Research (parallel × 2-3 omd-ux-researcher)
- Phase 3 — IA / Journey (master itself) → user checkpoint #1
- Phase 4 — Wireframe (spawn omd-ui-junior)
- Phase 5 — System Graph + portable DESIGN.md Core v2 projection patch → user checkpoint #2
- Phase 6 — Components (spawn omd-ui-junior)
- Phase 6.5 — Asset Sourcing (spawn omd-asset-curator)
- Phase 7 — Microcopy (spawn omd-microcopy)
- Phase 8 — Validation (spawn omd-a11y-auditor → cross-family jury → spawn omd-persona-tester × 4) → user checkpoint #3
- Iteration loop (cap 3) — spawn omd-critic between iterations
- Phase 9 — Handoff (zip packaging for v0/Cursor/Subframe)
- Spawn sub-agents via Codex's spawn-agent mechanism with names matching
.codex/agents/<name>.toml:omd-ux-researcheromd-asset-curatoromd-ui-junioromd-microcopyomd-a11y-auditoromd-persona-tester(×4 in parallel for Phase 8)omd-critic(iteration > 1)
- All artifacts go inside the run dir. Never write outside it except for
DESIGN.md(Phase 5, with user checkpoint approval) and.omd/preferences.md(viaomd remember).
User checkpoints (mandatory, do not auto-skip)
- Checkpoint #1 (Phase 3 end) — show
journey.mmd+screens.md(화면 인벤토리: 화면별 목적/핵심 요소/문법/상태/프리셋 후보 표), halt for user reply. 승인된 화면 목록 밖의 화면은 만들지 않는다. - Checkpoint #2 (Phase 5 end) — show
DESIGN.md.patch, halt. - Checkpoint #3 (Phase 8 end) — show validation summary, halt.
A non-mandatory informational checkpoint #0 follows Phase 1.5 (asset self/fallback/skip choice). All four are gated; do not bypass.
OmD apply (UI work outside the harness)
For ad-hoc UI work (component changes, microcopy edits, color tweaks) not running through the full harness:
- Read project-root
DESIGN.mdin full at the start of the turn. - Read
.omd/preferences.mdpendingentries — these override DESIGN.md until folded in. - Apply changes citing only DESIGN.md tokens (never invent).
- If the user corrects your design choice, run
omd remember "<one-sentence summary>" --context "<file>"before ending the turn.
This mirrors the omd:apply Claude Code skill behavior.
Browser execution for the restart tracks (2026-09-07 user preference)
- In Codex, prefer the connected Computer Use Chrome surface for live page interaction, login-state checks, media-service operation, and rendered QA. The global browser-harness skill's "Always use" description does not require choosing it over this user preference.
- Use browser-harness only when explicitly selected for a capability that Computer Use cannot provide and after checking that its connection works. Its CDP/remote-debugging setup is not a prerequisite for working Computer Use Chrome access.
- Grok Build and Claude Code do not automatically inherit Codex's Computer Use tools. For the benchmark, one shared browser operator must execute cell-scoped requests without adding creative advice; four model workers may run concurrently, but shared Chrome operations remain serialized.
- Keep each cell's prompts, tabs, results, and downloads separate. Do not expose the user's unrelated tabs/history or another arm's output to a worker. Browser capability access must be equal across all four conditions.
- A connected browser or an authenticated page alone does not prove that image/video generation, download, or the whole benchmark broker works. Verify each claimed capability through its actual flow.
- Computer Use currently rejects iTerm2 control. Do not route around that restriction through another UI/shell automation mechanism. Use the separately authorized CLI execution channel for model jobs.
Product surface ownership (mandatory)
- oh-my-design is a DESIGN.md archive plus frontend skills. The user-facing funnel is Home →
/design-systems/[id](the item page) → its#useaction group in the hero: Copy DESIGN.md and Download. The install command, the first prompt and the raw-.md link left the item page with its "how to use" section on 2026-10-20 (round 11, owner review #21–#23). Landing rows and search on/and/koopen the item page. Decided 2026-10-01 (IA D1–D4,docs/REDESIGN_DECISIONS_2026-10-01.md): the item page is where most bot/AI fetches and human requests already land, so the catalog's hand-off belongs there. Korean item pages shipped 2026-10-14 (D5, growth plan P2):/ko/design-systems/[id]exists for every Korean reference plus every verified one (web/src/lib/i18n/ko-detail.tsis the single predicate for routes, hreflang, sitemap and links), and/kokeycaps and search open it; anything outside that set keeps only its English page. The Korean page shows the canonical English DESIGN.md byte for byte under Korean chrome, names the brand by the registry's HanguldisplayNameor else the Englishname(never a transliteration), and its summary is a Korean sentence over values the page shows, never a translation. - In product discussions, “preview”, “미리보기”, and “사용자가 보는 화면” mean the item page's preview (
ReferencePreviewon/design-systems/[id]). There is no customize tool any more: “builder”, “빌더”, “Customize” or “커스터마이즈” in an old note or request refers to the removed/builder; read it as the item page and its#useactions. /design-systems/[id]carries the only indexed per-reference HTML and the JSON-LD (Article, BreadcrumbList; FAQPage was dropped on 2026-10-20 because the page no longer shows those answers as Q&A, and FAQ markup must mirror visible content), its one<h1>is “{Name} DESIGN.md” and its title “{Name} DESIGN.md — Colors, Typography, Components” (owner decision 3, 2026-10-20; URLs unchanged), andgenerateStaticParamscovers every reference. Changes to how a reference reads or is handed off belong here and are acceptance-tested through Home → brand row →/design-systems/<id>→#use./builderwas removed on 2026-10-13 (owner decision Q1, complete removal; the customize feature went with it). It survives only as a 308 Route Handler (web/src/app/builder/route.ts, table inweb/src/lib/legacy-builder/redirect.ts):/builder?ref=<known id>&…→/design-systems/<id>#use; no ref or an unknown ref →/design-systems. Those links sit inside prompts users have already pasted, so the redirect must keep resolving; do not rebuild a page at/builderor link to it./reference/[id]no longer exists; it 308s to/design-systems/[id](D4).ReferencePreviewrenders the item page's preview and does not render its brand name as a heading. Acceptance-test any change to it through the item page; route ownership is determined by the consumer journey, not the component filename.- Before finishing catalog UI work, verify Home → brand row →
/design-systems/<id>→#use(Copy DESIGN.md, Download), on/koas well as/.
Hard rules (apply across channels)
- Unknown means absent — at the smallest unresolved field/group boundary. oh-my-design is a reference delivery product, not a fallback generator. Never promote a plausible substitute, heuristic parse, generic component, system font, or adjacent corporate/marketing surface as a brand/product fact. Omit only the unresolved field, item, or wholly empty group on
/design-systems/[id]; preserve every other verified value, metric, description, and section from the canonical reference. - Never enforce absence by deleting or replacing the canonical reference body, collapsing a useful reference into a status document, or adding
Partial/warning chrome in place of its content. A missing font family removes that family/specimen, not verified typography metrics, spacing, colors, components, or explanations. - Reference depth is part of correctness. §1 must explain the company/product, distinctive brand expression, and current evolution using first-party history/rebrand/culture evidence; it must not read like an audit-scope disclaimer. §3 must distinguish official product-use, live surface-use, official distributed font assets, declared-only faces, and unresolved claims. A browser-unloadable but officially confirmed product font keeps its metadata and loses only the live specimen.
- Narrative evidence and UI-token evidence are related but not identical. An official font's history, visual character, or license can belong in the reference without being promoted to
tokens.typography.family.ui. Do not delete useful brand context merely because it is not a machine token. - Public marketing, corporate, font-catalog, and product/app surfaces are separate evidence domains. Observation on one domain cannot populate another domain's reference tokens without explicit evidence linking them.
- Unlabelled font substitution is forbidden (owner decision G3, 2026-10-13). Runtime availability never turns another face into the brand face: a known but non-loadable brand face keeps its metadata and is labeled unavailable. A substitute is allowed only when it is chosen by measurement (x-height ratio, average width, weight axis, classification), recorded per script (Latin / Hangul / Kana / Han) with its metrics and source, and labeled "substitute — not the brand face" wherever it is named or rendered; prefer Google Fonts faces so shadcn-style consumers can install them. A per-script safe default (Noto Sans, Noto Sans KR/JP/SC/TC) is labeled "safe default (not the brand face)". Never render Inter, system-ui, a substitute, or a safe default as though it were the brand face, and never choose a substitute by eye — with no measurement, write "Substitute: none chosen".
- Never fabricate brand, principle, or persona facts. Core v2 omits an unresolved
value at its smallest field/group boundary;
[FILL IN]is legacy-read compatibility only and must not be emitted by a new Core writer. - Never introduce a token absent from DESIGN.md without going through Phase 5 (system extension with checkpoint #2 approval).
- A component library is not a brand reference, and depth does not decide which one you have. A published design system belongs in the catalog when its name refers to a product or platform that exists apart from the system; it is a library when the name refers only to the toolkit. Check by opening that name's product page on the company's own domain with a nonsense path as a control —
bytedance.com/arcoreturns 200, and so doesbytedance.com/zz-this-does-not-exist, byte for byte. Without the control you will read a catch-all as a product. (Decided 2026-09-21 admitting Mitsubishi Electric's Serendie, which has a real platform site, while keeping TDesign, Arco, Semi, Vant and the rest out.) - Never download from Pinterest. Pinterest URLs are listed for the user to download manually.
- Never emit SUS / NPS / "satisfaction score" from synthetic personas. Use task_success / steps_vs_optimal / friction_count / heuristic_violations / abandonment instead.
- Never auto-skip user checkpoints.
- Never delete a run directory. They are permanent learning artifacts.
세션 연속성 프로토콜
- 시작, 그리고 컨텍스트가 요약(compact)된 뒤:
scripts/context_restore.sh를 실행한다(Claude Code는 SessionStart 훅이 자동으로 돌린다). 출력의 「지금」 블록에 있는 막힘과 대기부터 처리한다. - 체크포인트: 작업 단위를 끝내거나 결정이 확정되면
docs/CURRENT_STATE.md의 「지금」 블록을 먼저 고치고 나서 보고한다. 이 파일은 짧게 유지하고, 오래된 날짜 절은docs/archive/state/로 옮긴다. - 종료:
docs/JOURNAL.md맨 위에 항목을 추가한다(한 일/열린 것/다음, 5줄 이내). 채팅에만 있는 맥락은 잃어버린 것으로 본다. - 방향과 트랙의 정본은
docs/ROADMAP.md다.
Pre-existing OmD shims (managed by omd sync)
Below this line, omd sync may add a managed block with shim content for Claude Code / Cursor compat. Do not edit between the markers.
<!-- omd:start version=1 --><!-- omd:end -->Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

