/omd-init

name: omd:init
description: "프로젝트 루트에 DESIGN.md를 부트스트랩 — 실제 기업 레퍼런스 중 컨텍스트 매칭으로 추천하고 선택된 레퍼런스의 톤&매너를 보존한 variation을 생성. DESIGN.md 부재 상태에서의 UI 작업 또는 '디자인 시스템 세팅', 'set up our design system', 「デザインシステムを作って」, 「建立設計系統」류의 요청에 트리거. CLAUDE.md / AGENTS.md / Cursor rule shim도 함께 설치."

omd:init — DESIGN.md Bootstrap

프로젝트에 DESIGN.md + AI 코딩 에이전트용 shim 3종을 한 번에 세팅. 레퍼런스 톤&매너는 **preserve**하고, 사용자 프로젝트 맥락은 controlled-vocabulary delta_set으로만 반영.

레퍼런스 선택과 graph draft는 host agent 안에서 처리하지만, Core projection과 authority hash는 직접 만들지 않는다. 설치된 provider-free `omd design-md` 도구가 inspect/migrate/compile을 담당한다. `omd init recommend`, `omd init prepare`, `omd sync` 같은 별도 runtime subcommand는 제공하지 않는다.

전체 플로우

Phase 1: 사용자 맥락 파악 (1-2 질문)
Phase 2: 레퍼런스 추천 (fingerprint 기반 in-head 점수)
Phase 3: 사용자가 1개 선택
Phase 3.5: 적용 형태 확인 (루트 부트스트랩 / 참고용 저장 / 기존 파일 교체 여부)
Phase 4: 레퍼런스 DESIGN.md Read + delta_set 추출
Phase 4.5: 프로젝트 권위 입력 수집
Phase 5: Core v2 System Graph draft → canonical compiler → staged adopted package
Phase 6: Shim 3종 설치 (omd:sync skill 위임)
Phase 7: 요약 출력

Phase 1 — 맥락 파악

이미 충분한 description이 있으면 skip. 부족하면 **최대 2개** 질문:

1. 프로젝트 유형/도메인 (SaaS / 랜딩 / 대시보드 / 이커머스 / 커뮤니티 등) 2. 분위기 키워드 (warm, minimal, premium, playful, dense, airy 등)

한 번에 하나씩, 또는 통합해서 한 번에. 질문 쌓지 말 것.

Phase 2 — 레퍼런스 추천 (file-based, no CLI)

2.1 카탈로그 로드

다음 파일을 Read 툴로 전체 로드 (있는 순서대로 fallback):

1. `.codex/data/reference-fingerprints.json` (Codex 설치 카탈로그) 2. `.claude/data/reference-fingerprints.json` (Claude Code / Cursor 설치 카탈로그) 3. `.opencode/data/reference-fingerprints.json` (OpenCode 설치 카탈로그) 4. `node_modules/oh-my-design-cli/data/reference-fingerprints.json` (npm 설치 직접 경로) 5. `data/reference-fingerprints.json` (개발 환경)

스키마: `{ count, items: [{ id, primary_color_hex, category, visual_theme, voice_fingerprint, tone_keywords, antipatterns, signature_motion, has_personas, category_raw }] }`.

추가 보조 파일 (있으면 같이 로드):

• 위에서 실제 선택된 data dir의 `vocabulary.json` — controlled vocab axes/keywords
• 같은 data dir의 `reference-tags.md` — human-readable keyword matrix

필수 품질 파일:

• 같은 data dir의 `reference-quality.json` — `verified_v2 | partial | legacy_snapshot`

fingerprint는 있는데 품질 파일이 없거나 두 파일의 `count`/id 집합이 다르면 다른 채널 파일로 섞어 보완하지 않는다. `omd install-skills`를 다시 실행하고 `omd doctor`로 확인하라고 안내한 뒤 reference 추천을 중단한다.

채널을 알 수 있으면 해당 채널 data dir을 우선 사용하되, 파일이 없으면 위 1→5 순서로 fallback한다. 서로 다른 설치 채널의 fingerprint와 보조 파일을 섞지 말 것.

2.2 task 분석 (silent)

사용자의 description에서 다음 추출:

• **명시 brand hint**: 한글/영문 brand 이름 직접 언급 (예: "토스 같은" → `toss`, "뱅크샐러드 톤" → `banksalad`, "Linear-clone" → `linear.app`). brand 이름과 id 매핑은 일반 지식 사용 + `items[].id` 또는 `items[].category_raw`에서 cross-check.
• **vocab 키워드**: warm / minimal / dense / playful / formal / editorial / clinical 등 (vocabulary.json 참조)
• **카테고리 추측**: Consumer Tech / Fintech / Productivity / E-commerce / Design Tools / Developer Tools / AI & LLM / Mobility / HR / Real Estate / Healthcare / Government

2.3 로컬 query helper 실행 (deterministic)

현재 `SKILL.md`와 같은 skill directory의 `scripts/query-references.mjs`를 사용한다. Phase 2.1에서 선택한 단일 data dir을 `--data-root`로 넘기고, 사용자 원문을 `--task`, catalog에서 cross-check한 명시 brand id가 있으면 `--brand`로 넘긴다.

node <active-omd-init-skill-dir>/scripts/query-references.mjs \
  --data-root <selected-data-dir> \
  --task "<original user description>" \
  --limit 5 \
  --json

helper가 찾히지 않으면 과거 in-head scorer로 조용히 fallback하지 않는다. 설치가 stale한 것이므로 `omd install-skills` → `omd doctor`를 안내하고 중단한다.

결과 계약:

• `status: ok` → ordered `candidates`를 그대로 사용. 모델이 순서를 다시 매기지 않음.
• `status: needs_clarification` → 후보를 채워 넣지 말고 brand/category/tone 중 하나를 묻는다.
• 모든 candidate는 `quality.status`와 `promotion.token_policy`를 함께 표시한다.
• `verified_v2`도 증거가 있는 field만 사용하고 unknown은 가장 작은 단위로 생략한다.
• `partial`/`legacy_snapshot`은 `context-only-reverify-first`; reverify 없이 machine token이나

product fact로 승격하지 않는다.

• Vercel/Linear/Notion 같은 “safe fallback”을 임의로 추가하지 않는다.

2.4 사용자에게 제시

prose로:

"<task 핵심 한 줄>"을 보니 <top1.id>가 가장 잘 맞을 것 같아요 — <matched category/tone 핵심 한 줄> · <quality.status>.

이대로 가시려면 go (또는 <top1.id>).
다른 후보: <top2.id> (한 줄 이유) · <top3.id> (...) · <top4.id> (...) · <top5.id> (...)
본인이 아는 다른 reference 있으면 id로 알려주세요 (예: vercel) — 카탈로그에 없으면 알려드립니다.

vocab axis conflict 있으면 (예: formal ↔ playful) 먼저 알리고 우선시할 축을 묻기.

**Claude Code 채널이면 위 prose 대신 AskUserQuestion 툴 1개로 제시** (사용자가 화살표로 고르는 selectable UI — #21). question 1개에 top-5 후보 id 5개를 option으로:

question: ""<task 핵심 한 줄>"에 맞는 레퍼런스를 골라주세요"
header: "Reference"
options: top1~top5 각각 → label = <id>, description = query 근거 1줄 (<category> · <tone_keywords 1-2개> · <quality.status>)
  - top1에는 label에 "(추천)" 표시

(AskUserQuestion이 자동 "Other"를 추가하므로 카탈로그의 다른 id를 자유 입력으로 답하는 것도 그대로 가능.) Codex / OpenCode 등 AskUserQuestion이 없는 채널은 위 prose 포맷 유지. 점수 계산·채택 로직(Phase 3)은 어느 쪽이든 동일.

Phase 3 — 사용자 선택

• `go` 또는 top-5 안 id → 그 id 채택
• top-5 밖이지만 카탈로그 안 id → 그대로 채택
• 카탈로그에 없는 id → "해당 id는 카탈로그에 없어요. top-5 중에서 골라주세요."
• "중단" → 종료

선택된 candidate가 `partial` 또는 `legacy_snapshot`이면 곧바로 Phase 5로 가지 않는다. “참고용 저장” 또는 “먼저 reverify”만 제시한다. 사용자가 명시적으로 참고용을 선택하면 narrative inspiration으로만 저장하고, 해당 reference의 font/color/component를 프로젝트 brand fact나 machine token으로 표기하지 않는다.

Phase 3.5 — 적용 형태 확인

레퍼런스 확정 직후, 어떻게 적용할지 묻는다. 먼저 프로젝트 루트에 `DESIGN.md`가 이미 있는지 확인하고, **Claude Code 채널이면 AskUserQuestion 1개** (타 채널은 prose)로:

• 루트에 DESIGN.md **없음**:

1. **프로젝트 디자인 시스템으로 설정 (추천)** — `<id>` 톤을 보존한 변형본을 루트 `DESIGN.md`로 부트스트랩 (Phase 4~7 전체 진행) 2. **참고용으로만 저장** — 루트 변경 없음. `<id>` 원본을 `design-references/<id>.md`로 복사하고 종료. "나중에 프로젝트에 적용하려면 다시 omd:init을 불러주세요" 안내. (변형 생성·셤 설치 안 함)

• 루트에 DESIGN.md **이미 있음** (option description에 그 파일의 첫 섹션 요약

한 줄을 보여줄 것): 1. **교체 (추천)** — 기존 파일은 먼저 lossless migration/check를 통과하고 content-addressed rollback artifact로 보존됨을 명시 2. **참고용으로만 저장** — 위와 동일 3. **중단**

②(참고용) 선택 시: Phase 4.1로 원문만 확보해 `design-references/<id>.md`에 attribution 1줄(소스 URL + 날짜)과 함께 저장 → Phase 7 요약만 출력하고 종료. Phase 4.2~6은 건너뛴다.

##