agentleFS
kwakseongjaekwakseongjae/oh-my-design/AGENTS.md

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: -…

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
  1. Very specific:

    When this AGENTS.md is loaded and a fresh .omd/runs/run-<latest>/ exists:

    line 51
  2. Very specific:

    Activate the orchestrator persona: Read .codex/agents/omd-master.toml and adopt that role.

    line 53
  3. Very specific:

    All artifacts go inside the run dir: Never write outside it except for DESIGN.md (Phase 5, with user checkpoint approval) and …

    line 78
  4. Very specific:

    Read project-root DESIGN.md in full at the start of the turn.

    line 94
  5. Very specific:

    Read .omd/preferences.md pending entries — these override DESIGN.md until folded in.

    line 95
  6. Very specific:

    If the user corrects your design choice, run omd remember "<one-sentence summary>" --context "<file>" before ending the turn.

    line 97
  7. Distinctive:

    Use browser-harness only when explicitly selected for a capability that Computer Use cannot provide and after checking that its connection …

    line 104
  8. Distinctive:

    Keep each cell's prompts, tabs, results, and downloads separate.

    line 106
  9. Very specific:

    Before finishing catalog UI work, verify Home → brand row → /design-systems/<id> → #use (Copy DESIGN.md, Download), on /ko as well as /.

    line 118
  10. Very specific:

    Never fabricate brand, principle, or persona facts.

    line 128
  11. Distinctive:

    Never introduce a token absent from DESIGN.md without going through Phase 5 (system extension with checkpoint #2 approval).

    line 131
  12. Distinctive:

    Never download from Pinterest.

    line 133
  13. Distinctive:

    Never emit SUS / NPS / "satisfaction score" from synthetic personas.

    line 134
  14. Distinctive:

    Never auto-skip user checkpoints.

    line 135
  15. Distinctive:

    Never delete a run directory.

    line 136

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

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 the omd CLI (bin/oh-my-design.ts is 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 under web/ because the Vercel project root is web/ (the site build can only read files beneath it). The root references symlink, design-md/, and packages/mcp/data/references/ are all derived from here. Rule: edit web/references/ only.
  • skills/omd-* — Claude Code / Codex / OpenCode skill files (installed into target projects via omd 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, while reference-evidence/ (145MB of capture bundles) and reverify/ 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.json records per-file SHA-256s and node scripts/local-store.mjs --verify checks 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 by omd-harness Step 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:

  1. Activate the orchestrator persona. Read .codex/agents/omd-master.toml and adopt that role. The full behavioral spec lives at .claude/agents/omd-master.md — follow it verbatim regardless of channel.
  2. Run the 10 phases in order (see .claude/agents/omd-master.md for 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)
  3. Spawn sub-agents via Codex's spawn-agent mechanism with names matching .codex/agents/<name>.toml:
    • omd-ux-researcher
    • omd-asset-curator
    • omd-ui-junior
    • omd-microcopy
    • omd-a11y-auditor
    • omd-persona-tester (×4 in parallel for Phase 8)
    • omd-critic (iteration > 1)
  4. 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 (via omd 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:

  1. Read project-root DESIGN.md in full at the start of the turn.
  2. Read .omd/preferences.md pending entries — these override DESIGN.md until folded in.
  3. Apply changes citing only DESIGN.md tokens (never invent).
  4. 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 #use action 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 /ko open 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.ts is the single predicate for routes, hreflang, sitemap and links), and /ko keycaps 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 Hangul displayName or else the English name (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 (ReferencePreview on /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 #use actions.
  • /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), and generateStaticParams covers 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.
  • /builder was 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 in web/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 /builder or link to it.
  • /reference/[id] no longer exists; it 308s to /design-systems/[id] (D4).
  • ReferencePreview renders 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 /ko as 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/arco returns 200, and so does bytedance.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 -->

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.