oh-my-design-cli 0.1.3 → 1.0.1

package/package.json

@@ -1,45 +1,48 @@
 {
   "name": "oh-my-design-cli",
-  "version": "0.1.3",
-  "description": "Interactive CLI to generate DESIGN.md files for AI coding agents",
+  "version": "1.0.1",
+  "description": "Bootstrap oh-my-design skills + agents into your project. After install, talk to your AI coding agent in natural language — no other CLI commands.",
   "type": "module",
   "bin": {
     "oh-my-design": "dist/bin/oh-my-design.js",
     "omd": "dist/bin/oh-my-design.js"
   },
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "exports": {
-    ".": {
-      "import": "./dist/index.js",
-      "types": "./dist/index.d.ts"
-    }
-  },
   "files": [
     "dist",
-    "templates",
-    "skills",
+    "skills/omd-apply",
+    "skills/omd-init",
+    "skills/omd-harness",
+    "skills/omd-learn",
+    "skills/omd-remember",
+    "skills/omd-sync",
+    "agents",
     "data",
-    "references/**/DESIGN.md"
+    "references/**/DESIGN.md",
+    ".claude/hooks/*.cjs",
+    ".claude/settings.json",
+    "AGENTS.md",
+    "scripts/postinstall.cjs",
+    "scripts/context.cjs"
   ],
   "scripts": {
-    "build": "tsup && cp -r src/templates dist/templates",
+    "build": "tsup",
     "dev": "tsup --watch",
     "start": "node dist/bin/oh-my-design.js",
     "test": "vitest run",
     "test:watch": "vitest",
     "lint": "tsc --noEmit",
     "prepare": "npm run build",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build",
+    "postinstall": "node scripts/postinstall.cjs"
   },
   "keywords": [
     "design-system",
     "design-md",
-    "shadcn",
-    "cli",
     "ai-agent",
+    "claude-code",
+    "codex",
+    "skills",
     "google-stitch",
-    "design-tokens",
     "vibe-coding"
   ],
   "license": "MIT",
@@ -53,9 +56,7 @@
   "dependencies": {
     "@clack/prompts": "^0.9.1",
     "commander": "^13.1.0",
-    "handlebars": "^4.7.8",
-    "picocolors": "^1.1.1",
-    "zod": "^3.24.2"
+    "picocolors": "^1.1.1"
   },
   "devDependencies": {
     "@types/node": "^22.13.10",

package/scripts/context.cjs

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+// scripts/context.cjs — minimal, deterministic project scan invoked by the
+// omd-harness skill / omd-master agent when they want a fast .omd/context.json
+// without doing a full Glob+Read pass in prose.
+//
+// Output: writes .omd/context.json with { kind, framework, css_files,
+// package_name, deps_summary, ts }, and prints the path to stdout.
+//
+// Pure node — no deps. ~80 lines. Optional helper, not load-bearing: master
+// can also just Glob+Read inline, but this preserves determinism for repeat
+// scans across runs.
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const cwd = process.argv[2] || process.cwd();
+const out = path.join(cwd, '.omd', 'context.json');
+
+function safeRead(p) {
+  try {
+    return fs.readFileSync(p, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+function listFiles(dir, exts, max = 50) {
+  const found = [];
+  function walk(d, depth) {
+    if (depth > 4 || found.length >= max) return;
+    let entries;
+    try {
+      entries = fs.readdirSync(d, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      if (e.name.startsWith('.') || e.name === 'node_modules' || e.name === 'dist') continue;
+      const full = path.join(d, e.name);
+      if (e.isDirectory()) walk(full, depth + 1);
+      else if (exts.some((ext) => e.name.endsWith(ext))) {
+        found.push(path.relative(cwd, full));
+        if (found.length >= max) return;
+      }
+    }
+  }
+  walk(dir, 0);
+  return found;
+}
+
+const pkgRaw = safeRead(path.join(cwd, 'package.json'));
+const pkg = pkgRaw ? JSON.parse(pkgRaw) : null;
+const deps = pkg ? Object.assign({}, pkg.dependencies, pkg.devDependencies) : {};
+
+let framework = 'unknown';
+if (deps['next']) framework = 'next';
+else if (deps['vite']) framework = 'vite';
+else if (deps['react']) framework = 'react';
+else if (deps['vue']) framework = 'vue';
+else if (deps['svelte']) framework = 'svelte';
+else if (deps['solid-js']) framework = 'solid';
+
+let kind = 'unknown';
+if (pkg) kind = 'node';
+if (fs.existsSync(path.join(cwd, 'index.html')) && !pkg) kind = 'static-html';
+
+const cssFiles = listFiles(cwd, ['.css', '.scss', '.sass'], 20);
+const componentFiles = listFiles(cwd, ['.tsx', '.jsx', '.vue', '.svelte'], 30);
+
+const ctx = {
+  kind,
+  framework,
+  package_name: pkg?.name ?? null,
+  deps_summary: {
+    has_tailwind: !!deps['tailwindcss'],
+    has_shadcn: !!deps['@shadcn/ui'] || !!deps['shadcn-ui'],
+    has_recharts: !!deps['recharts'],
+    has_chartjs: !!deps['chart.js'] || !!deps['chartjs'],
+    has_d3: !!deps['d3'],
+    has_lucide: !!deps['lucide-react'] || !!deps['lucide-vue'] || !!deps['lucide'],
+    has_heroicons: !!deps['@heroicons/react'] || !!deps['@heroicons/vue'],
+    has_framer_motion: !!deps['framer-motion'],
+  },
+  css_files: cssFiles,
+  component_files: componentFiles.slice(0, 10),
+  ts: new Date().toISOString(),
+};
+
+fs.mkdirSync(path.dirname(out), { recursive: true });
+fs.writeFileSync(out, JSON.stringify(ctx, null, 2), 'utf8');
+process.stdout.write(out + '\n');

package/scripts/postinstall.cjs

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+// Friendly post-install nudge — only when the user explicitly installed
+// oh-my-design-cli (global or as a top-level dependency).
+//
+// Suppressed when:
+//   - running inside CI
+//   - this package is being installed as a sub-dependency
+//   - npm is in production mode
+//
+// Plain CommonJS so it runs on any Node version without build deps.
+
+'use strict';
+
+if (
+  process.env.CI ||
+  process.env.NODE_ENV === 'production' ||
+  // Sub-dep install: npm sets npm_command but no INIT_CWD pointing here
+  process.env.npm_config_global !== 'true' && !process.env.INIT_CWD
+) {
+  process.exit(0);
+}
+
+const c = {
+  bold: (s) => `\x1b[1m${s}\x1b[0m`,
+  cyan: (s) => `\x1b[36m${s}\x1b[0m`,
+  green: (s) => `\x1b[32m${s}\x1b[0m`,
+  dim: (s) => `\x1b[2m${s}\x1b[0m`,
+};
+
+const lines = [
+  '',
+  `${c.green('✓')} ${c.bold('oh-my-design installed.')}  ${c.dim('(commands: omd, oh-my-design)')}`,
+  '',
+  `  ${c.bold('Next')}  in any project:`,
+  '',
+  `    ${c.cyan('cd')} ${c.dim('<your project>')}`,
+  `    ${c.cyan('omd install-skills')}        ${c.dim('# one time per project — installs the design harness')}`,
+  '',
+  `  ${c.bold('Then open Claude Code (or Codex). Just say what you want:')}`,
+  '',
+  `    ${c.dim('"토스 스타일 가족 식단 공유 앱 메인 화면 디자인해줘"')}`,
+  `    ${c.dim('"Linear-clone B2B SaaS dashboard 만들고 싶어"')}`,
+  `    ${c.dim('"이 카드 좀 더 세련되게"')}`,
+  '',
+  `  ${c.bold('하네스가 알아서 호출됨')} ${c.dim('— Claude Code hook이 디자인 요청 감지해서 자동 라우팅. 별도 슬래시 안 쳐도 됩니다.')}`,
+  '',
+  `  ${c.dim('Power user shortcut: ')} ${c.cyan('/omd-harness <task>')} ${c.dim('— hook 우회하고 즉시 진입.')}`,
+  '',
+  `  ${c.bold('⚠ Already running Claude Code?')} ${c.dim('Quit (Cmd+Q on macOS) and relaunch — subagents only load at session start.')}`,
+  '',
+];
+
+console.log(lines.join('\n'));
+

package/skills/omd-apply/SKILL.md

@@ -1,85 +1,96 @@
 ---
 name: omd:apply
-description: "프로젝트 루트의 DESIGN.md를 UI/스타일링/마이크로카피/모션 작업의 authoritative brand context로 적용합니다. 컴포넌트 만들기, CSS 수정, 카피 작성, 애니메이션 튜닝, 디자인 시스템 질문에 트리거됩니다. 사용자 교정이 발생하면 자동으로 omd remember를 호출해 preference log에 기록합니다."
+description: "프로젝트 DESIGN.md를 UI/시각 작업의 brand context로 적용. 컴포넌트·색상·폰트·레이아웃 수정 같은 구체적 요청과 톤·분위기 표현 — KR '좀 더 따뜻하게', EN 'make it warmer/cooler', 日本語「もう少し暖かく」, 繁體中文「更溫暖一點」 — 모두에 트리거. DESIGN.md 부재 시 omd:init 우선. 화면 전체 신규 디자인은 omd:harness, 교정 기록은 omd:remember."
 ---
 
-# omd:apply — Brand Context Injection
+# omd:apply — Brand Context Injection + Dispatch Router
 
-프로젝트 루트의 `DESIGN.md`를 읽고, UI 관련 모든 작업의 authoritative brand context로 사용한다. 작업 도중 사용자가 디자인 선택을 교정하면 `.omd/preferences.md`에 자동 기록한다.
+DESIGN.md를 모든 UI/디자인 작업의 권위 있는 컨텍스트로 사용한다. 단일 책임은 두 가지:
+
+1. **인라인 처리** — 작은 단일 변경 (1 component, 1 token, 1 카피 라인)은 직접 Edit 툴로 처리
+2. **Dispatch** — 복합 작업은 적합한 서브에이전트로 즉시 라우팅 (master 거치지 않음)
+
+복합 작업을 인라인으로 처리하면 안 된다. 이 스킬의 가장 중요한 책임은 *언제 dispatch할지 정확히 판단하는 것*.
 
 ## 트리거 조건
 
 다음 중 하나가 감지되면 SKILL 전체를 로드한다.
-- 새 컴포넌트 생성 (button, card, dialog, nav, form 등)
-- 기존 컴포넌트 스타일 변경 (Tailwind 클래스, CSS, 토큰 값)
-- 마이크로카피 작성/수정 (버튼 라벨, empty state, 에러 메시지, tooltip)
-- 모션/트랜지션 추가
-- 색상·타이포그래피·스페이싱 조정
-- 디자인 시스템 관련 질문
-
-## Phase 1 — DESIGN.md 로드
 
-작업 시작 전:
+- 컴포넌트 생성 / 수정 (button, card, dialog, nav, form 등)
+- 스타일 변경 (Tailwind 클래스, CSS, 토큰 값)
+- 마이크로카피 작성 / 수정 (버튼 라벨, empty state, 에러, tooltip)
+- 모션 / 트랜지션 추가
+- 색상 · 타이포그래피 · 스페이싱 조정
+- 에셋 (아이콘, 차트, 일러스트, 3D 렌더) 요청
+- 디자인 시스템 관련 질문
 
-1. 프로젝트 루트의 `DESIGN.md`를 **전체 읽는다**. 요약하지 말고 실제 파일 내용을 Read 툴로 로드.
-2. `.omd/preferences.md`가 있으면 함께 읽는다. `status: pending` 엔트리들은 아직 DESIGN.md에 반영 안 된 교정사항 — **이들을 DESIGN.md보다 우선** 적용한다.
-3. Precedence 순서:
-   ```
-   .omd/preferences.md (pending) > DESIGN.md > framework defaults
-   ```
+## Phase 0 — Dispatch decision tree (가장 먼저)
 
-DESIGN.md가 없으면 사용자에게 알리고 `omd init` 제안. 임의 생성하지 말 것.
+작업 시작 전에 어떤 처리 경로인지 결정한다. 다음 표를 위에서부터 순차 매칭, 첫 번째 매칭 행으로 진행:
 
-## Phase 2 — Brand Context 적용
+| 사용자 요청 패턴 | 처리 경로 | 이유 |
+|---|---|---|
+| "에셋 / 아이콘 / 일러스트 / 차트 / 사진 / 로고 / 그래프 / SVG 만들어" | dispatch `omd-asset-curator` | 매체 선택 + 스택 매칭이 전문 영역 |
+| "3D / 렌더 / 블렌더 / 목업" 명시 | dispatch `omd-3d-blender` | Blender MCP 필요 |
+| "메인 화면 / landing / 전체 디자인 / 처음부터 / 와이어프레임" | 사용자에게 `/omd-harness` 추천 | 10-phase 파이프라인이 적합 |
+| "접근성 / a11y / 색약 / 키보드 네비" 감사 | dispatch `omd-a11y-auditor` | 전문 감사 |
+| "마이크로카피만 다듬어 / 카피 톤 정리 / empty state 문구 전부" 복수 | dispatch `omd-microcopy` | voice 일관성 |
+| "사용자 시나리오 / 페르소나 walk through / 4명 입장에서 검토" | dispatch `omd-persona-tester` | adversarial 4-페르소나 |
+| "이 카피 좋은지 / hero 카피 약점 / 섹션별 카피 전문가 의견 / A/B 후보" | dispatch `omd-ux-writer` | UX writing 분석 + 대안 + 근거 |
+| "이 인터랙션 / 모션 / 포커스 / 모바일 / 지각 성능 / 섹션별 UX 약점" | dispatch `omd-ux-engineer` | 코드 레벨 인터랙션 감사 + fix |
+| "랜딩 / 메인 화면 / 페이지 *전체*를 전문가 의견으로 개선" | dispatch `omd-ux-writer` + `omd-ux-engineer` (병렬) | 두 트랙 동시 — writing + engineering |
+| "이게 왜 안 좋은지 critique / postmortem / root cause" | dispatch `omd-critic` | 비판적 분석 |
+| "DESIGN.md 만들어 / reference 골라 / 67개 중 추천" | dispatch `omd-init` skill (또는 omd-add-reference) | reference 매칭 |
+| "preference 정리 / 누적된 교정 반영 / DESIGN.md 업데이트" | dispatch `omd-learn` skill | fold-in 로직 |
+| "이 한 줄 / 이 컬러 / 이 spacing 좀" 단발 명확 | **인라인 처리** | 분명한 단일 변경 |
+| 위 어디에도 안 맞는 자유로운 디자인 작업 | 인라인 처리 후 Phase 3 (교정 캡처) | 일반 케이스 |
 
-작업 전체에서 다음 규칙 강제:
+dispatch가 정해지면 즉시 Agent 툴 호출 (master 경유 X — 우리가 omd-apply로 트리거됐다는 건 master 컨텍스트 밖이라는 의미). 그 후 인라인 처리는 하지 않고, 서브에이전트가 반환한 결과를 사용자에게 정리만 해서 전달.
 
-- **Token 값은 DESIGN.md에서만 인용한다.** 임의 hex, 임의 spacing 값, 임의 radius 사용 금지.
-- **Voice 섹션을 마이크로카피에 적용한다.** 문장 길이, 어휘 register, 은유 밀도를 DESIGN.md의 Voice 섹션에 맞춘다.
-- **Component 섹션에 명시된 규칙을 따른다.** 해당 컴포넌트 섹션이 있으면 variant / state / sizes를 그대로 사용.
-- **없는 토큰을 지어내지 않는다.** DESIGN.md에 없는 스펙이 필요하면 사용자에게 "이건 DESIGN.md에 없는데, 어떻게 할까요?" 물어본다.
+## Phase 1 — DESIGN.md 로드 (인라인 처리 분기 한정)
 
-## Phase 3 — 교정 캡처 (Self-Report)
+dispatch가 아니라 인라인 처리로 분기됐을 때만 진행:
 
-**이것이 omd:apply의 차별화 포인트다. 반드시 수행.**
+1. 프로젝트 루트의 `DESIGN.md`를 **전체 읽는다**. 요약 금지, Read 툴로 직접 로드.
+2. `.omd/preferences.md`가 있으면 같이 읽는다. `status: pending` 엔트리는 아직 DESIGN.md에 반영 안 된 교정 — DESIGN.md보다 **우선** 적용.
+3. 우선순위:
+   ```
+   .omd/preferences.md (pending) > DESIGN.md > framework defaults
+   ```
 
-턴을 끝내기 전, 이번 턴에 다음 중 하나라도 발생했는지 확인한다:
+DESIGN.md 없으면 사용자에게 알리고 omd:init 스킬 트리거. 임의 생성 금지.
 
-1. 사용자가 당신의 디자인 선택을 명시적으로 교정 ("no, use X", "actually, Y", "don't use Z", "we never do W")
-2. 사용자가 당신이 쓴 토큰/값을 revert하거나 다른 값으로 교체
-3. 사용자가 "우리는 ~한다/하지 않는다" 형태의 디자인 원칙을 언급
+## Phase 2 — Brand Context 적용
 
-감지되면 턴 종료 전에 **반드시** 다음 커맨드를 Bash 툴로 실행:
+- 토큰 값은 DESIGN.md에서만 인용. 임의 hex / spacing / radius 금지.
+- Voice 섹션을 마이크로카피에 적용. 문장 길이, 어휘 register, 은유 밀도 일치.
+- Component 섹션 명시된 규칙 따름 (variant / state / sizes).
+- 없는 토큰 지어내지 않음. 필요 시 사용자에게 "이건 DESIGN.md에 없는데, 어떻게 할까요?" 묻기.
 
-```bash
-omd remember "<교정 내용을 한 문장으로 요약>" --context "<수정된 파일 경로 또는 사용자 발화 요약>"
-```
+## Phase 3 — 교정 캡처
 
-`--agent` 플래그는 생략한다. CLI가 환경변수(`CLAUDECODE`, `CODEX_SESSION_ID`, `OPENCODE` 등)로 자동 감지한다. 명시 override가 필요한 경우만 `--agent <name>`.
+턴 종료 전에 다음 중 하나가 있었는지 확인:
 
-예시:
-- 사용자: "CTAs는 절대 uppercase 쓰지 마"
-  → `omd remember "CTA buttons must never use uppercase text"`
-- 사용자가 `bg-brand-600`을 `bg-brand-500`으로 직접 바꿈
-  → `omd remember "primary CTA background should be brand-500, not brand-600" --context "src/components/Button.tsx"`
-- 사용자: "우리는 4pt grid가 아니라 8pt 써"
-  → `omd remember "spacing scale uses 8pt base, not 4pt"`
+1. 사용자가 디자인 선택을 명시적 교정 ("no, use X", "actually, Y", "don't use Z", "we never do W")
+2. 사용자가 토큰/값을 revert 또는 교체
+3. 사용자가 "우리는 ~한다/하지 않는다" 형태 원칙 언급
 
-scope는 note 내용에서 자동 추론된다 (keyword-based). 명시적으로 override가 필요하면 `--scope <value>` 추가 (e.g. `components.button`, `color`, `spacing`, `typography`, `voice`, `motion`, `layout`, `visualTheme`).
+감지되면 **omd:remember 스킬을 트리거**한다 (CLI 호출 X — `.omd/preferences.md`에 직접 append). 트리거 메서드: omd-remember SKILL.md의 Step 1-6 절차를 따라 Edit 툴로 파일 수정.
 
-## Phase 4 — 확인 메시지 (간결)
+## Phase 4 — 확인 메시지
 
-교정을 기록했을 때만 턴 끝에 한 줄로 알린다:
+교정 기록 시 턴 끝에 한 줄:
 
 ```
-📝 Logged to .omd/preferences.md — run `omd learn` to review, `omd learn --apply` to fold into DESIGN.md.
+Logged to .omd/preferences.md — say "preference 정리해줘" later to fold into DESIGN.md.
 ```
 
-일반 작업에서는 이 메시지 불필요. 과하게 알리지 말 것.
+일반 작업에는 불필요. 과한 알림 금지.
 
-## 금지 사항
+## 금지
 
-- DESIGN.md가 없는데 임의로 생성하지 말 것 (사용자에게 `omd init` 제안).
-- preferences.md에 직접 쓰지 말 것. 항상 `omd remember` 커맨드를 경유.
-- 교정 감지 시 사용자에게 "기록할까요?" 묻지 말 것. 자동 기록 → 사후 한 줄 알림.
-- 같은 턴 내에서 같은 교정을 중복 기록하지 말 것.
+- DESIGN.md 없는데 임의 생성 금지 (사용자에게 omd:init 제안)
+- 복합 작업을 인라인으로 처리 금지 (Phase 0 dispatch table 따라 라우팅)
+- 교정 감지 시 "기록할까요?" 묻지 말 것 — 자동 기록 + 한 줄 알림
+- 같은 턴 내 같은 교정 중복 기록 금지
+- CLI 호출 (`omd remember`, `omd learn` 등) 금지 — 1.0.0부터 모두 스킬 prose

package/skills/omd-harness/SKILL.md

@@ -0,0 +1,271 @@
+---
+name: omd:harness
+description: "화면 전체나 신규 surface를 처음부터 디자인할 때의 진입점 — Discovery→Wireframe→Components→Microcopy→Validation 파이프라인을 omd-master 오케스트레이터로 실행. '랜딩 처음부터', 'production-ready', 'wireframe to production', 「一からデザイン」, 「從頭設計」류의 요청에 트리거. 단일 컴포넌트 수정은 omd:apply."
+---
+
+# omd:harness — Design Harness Entry
+
+이 스킬은 **omd-master 오케스트레이터**를 호출하는 단일 진입점이다. 본 스킬은 launcher + 사전체크 + run 디렉토리 부트스트랩 책임만 가지고, phase 로직은 `agents/omd-master.md`에 있다.
+
+CLI 의존 없음. 모든 부트스트랩은 Bash + Write 툴로 직접 실행한다.
+
+## 트리거
+
+- `/omd-harness <task>` 명시 호출
+- 사용자가 자연어로 "디자인 하네스 / 시니어 디자이너처럼 / 알아서 디자인" 요청
+
+## Step 0 — task 추출
+
+슬래시에 task 같이 적었으면 (`/omd-harness 물 음용 유도 메인 화면`) 그 자연어 부분이 task. 빈 슬래시면 한 번 묻기:
+
+```
+어떤 디자인 작업을 진행할까요?
+shape: "[도메인] + [톤/스타일] + [핵심 화면]" — 예: "토스 스타일 가족용 식단 앱 메인 화면"
+```
+
+## Step 1 — Subagent registration 사전체크 (CRITICAL)
+
+`omd-master` subagent가 이 세션에 dispatch 가능한지 verify. Agent tool의 사용 가능 subagent 목록에 `omd-master`가 있으면 진행. 없으면:
+
+```
+omd-master subagent가 이 세션에 등록되어 있지 않아요. Claude Code는 세션 시작 시점에만 .claude/agents/*.md를 로드합니다 — install-skills를 세션 띄운 후에 돌렸으면 이 케이스.
+
+해결 (가장 빠른 순서):
+1. 현재 세션에서 /agents 실행 — Claude Code가 .claude/agents/*.md 강제 재스캔. omd-* 8개가 목록에 나타나면 /omd-harness 재호출.
+2. 안 되면: Claude Code 앱 완전 종료 (Cmd+Q / 터미널 자체 quit) → 새 터미널 → claude 재실행 → /omd-harness <task> 재호출.
+```
+
+## Step 2 — Run 디렉토리 부트스트랩 (인라인 Bash)
+
+이전엔 `omd harness "<task>" --internal` CLI를 호출했지만 1.0.0부터는 스킬이 직접 한다. 결정론적 hard verify gate:
+
+### 2.1 기존 run 재사용 체크
+
+```bash
+ls -t .omd/runs 2>/dev/null | head -1
+```
+
+출력 있으면 그 디렉토리의 `task.md`를 Read해서 사용자 task와 의미적으로 일치하는지 확인. 일치하면 그 run 재사용 — Step 3으로 점프.
+
+### 2.2 신규 run 부트스트랩
+
+다음을 **반드시 정확히 이 순서로** Bash 툴로 실행:
+
+```bash
+# 2.2.1 — timestamp + slug 결정 (한국어 보존)
+TS=$(node -e "console.log(new Date().toISOString().replace(/[:.]/g,'-'))")
+SLUG=$(node -e "
+const s = process.argv[1].toLowerCase().trim()
+  .replace(/[^a-z0-9가-힣\s-]+/g,'')
+  .replace(/\s+/g,'-')
+  .replace(/-+/g,'-')
+  .replace(/^-|-$/g,'');
+console.log(s.slice(0,40) || 'untitled');
+" "<EXTRACTED_TASK>")
+RUN_ID="run-${TS}-${SLUG}"
+RUN_DIR=".omd/runs/${RUN_ID}"
+
+# 2.2.2 — 표준 서브폴더 생성
+mkdir -p "${RUN_DIR}"/{wireframes,components,assets/briefs,assets/fallback,assets/pinterest-refs,eval/screenshots,persona-feedback,handoff,checkpoints}
+
+# 2.2.3 — task.md
+cat > "${RUN_DIR}/task.md" <<EOF
+# Harness Task
+
+<EXTRACTED_TASK>
+
+---
+
+- run_id: \`${RUN_ID}\`
+- started_at: $(date -u +%Y-%m-%dT%H:%M:%SZ)
+- cwd: \`$(pwd)\`
+EOF
+
+# 2.2.4 — run.log
+echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] run initialized" > "${RUN_DIR}/run.log"
+
+# 2.2.5 — .omd/.gitignore (idempotent)
+mkdir -p .omd
+[ -f .omd/.gitignore ] || printf "runs/\ncache/\n" > .omd/.gitignore
+
+# 2.2.6 — INDEX.md (idempotent header + append)
+INDEX=".omd/runs/INDEX.md"
+[ -f "${INDEX}" ] || cat > "${INDEX}" <<EOF
+# Harness Runs Index
+
+One line per run. Append-only.
+
+EOF
+TASK_ONELINE=$(echo "<EXTRACTED_TASK>" | tr '\n' ' ' | cut -c1-120)
+echo "- $(date -u +%Y-%m-%dT%H:%M:%SZ) \`${RUN_ID}\` — ${TASK_ONELINE}" >> "${INDEX}"
+
+# 2.2.7 — 결과 출력 (이 스킬이 파싱)
+echo "RUN_DIR=${RUN_DIR}"
+echo "RUN_ID=${RUN_ID}"
+```
+
+### 2.3 Hard verify gate (master spawn 차단 조건)
+
+부트스트랩 다음, master spawn 전에 반드시:
+
+```bash
+test -d "${RUN_DIR}" && test -f "${RUN_DIR}/task.md" && echo "OK" || echo "FAIL"
+```
+
+`OK`가 출력되지 않으면 master는 절대 spawn하지 않는다. 사용자에게:
+
+```
+하네스 부트스트랩이 실패했어요 (run dir or task.md 누락). 디스크 권한·경로 문제일 수 있어요. 다시 시도하거나 .omd/ 디렉토리를 정리해주세요.
+```
+
+이 gate를 통과해야만 Step 3로.
+
+## Step 3 — DESIGN.md 존재 확인 + reference 의미 매칭
+
+프로젝트 루트에 DESIGN.md 없으면 reference를 직접 추천한다. 외부 API 호출 없음.
+
+### 3.1 카탈로그 로드
+
+다음 파일을 Read 툴로 전체 로드:
+
+- `.claude/data/reference-fingerprints.json` — 67개 reference의 fingerprint (tone keywords, visual theme, antipatterns, signature motion, has_personas, category)
+- `.claude/data/reference-tags.md` — 사람-읽기용 keyword 매트릭스
+- `.claude/data/vocabulary.json` — controlled vocab
+
+`.claude/data/`에 없으면 `node_modules/oh-my-design-cli/data/` 또는 패키지 root `data/` 에서 fallback.
+
+### 3.2 사용자 task 분석 (silent)
+
+- controlled-vocab 키워드 추출 (예: "헬스/웰니스 / calm-blue / 차분" → `[calm, minimal, approachable, warm]`)
+- 명시 brand hint (예: "토스 같은" → `["toss"]`)
+- 카테고리 추측 (Consumer / Productivity / Fintech / AI / Developer Tools / Design Tools / Automotive / Aerospace / SaaS / Enterprise)
+
+### 3.3 점수 계산 (in-head, 결정론적)
+
+- 각 ref의 `tone_keywords` ∩ task keywords → 1점/매칭
+- brand hint match → +5점
+- 카테고리 일치 → +1점
+- top 5 정렬
+
+### 3.4 검증 (hallucination 방지)
+
+추천하는 모든 id는 `reference-fingerprints.json`의 `items[].id`에 **반드시** 존재해야 한다. 없는 id는 만들어내지 않는다.
+
+### 3.5 사용자에게 제시 (자연어 prose)
+
+라벨 없이, 추천을 statement로:
+
+```
+DESIGN.md가 없어서 reference 한 개를 골라 부트스트랩할게요. <task 핵심 한 줄>을 보니 <top1.id>가 가장 잘 맞을 것 같아요 — <visual_theme 핵심 + 매칭 키워드 1-2개를 한 줄로>.
+
+이대로 가시려면 go (또는 <top1.id>).
+다른 후보: <top2.id> (한 줄 이유) · <top3.id> (...) · <top4.id> (...) · <top5.id> (...)
+본인이 아는 다른 reference면 한 줄로 id만 (예: vercel) — 67개 카탈로그에 없으면 알려드립니다.
+```
+
+### 3.6 사용자 응답 처리
+
+- `go` 또는 reference id (top-5 안) → 그 id로 master spawn
+- 다른 reference id (top-5 밖이지만 카탈로그 안) → 동일하게 진행
+- 카탈로그에 없는 id → "해당 id는 67개 카탈로그에 없어요. top-5 중에서 골라주세요."
+- `중단` → 종료
+
+## Step 4 — Master 호출 (handoff loop)
+
+Subagent (master)는 AskUserQuestion 직접 호출 불가 (main-thread 전용). file-based handoff 패턴으로 돌린다.
+
+### 루프 의사코드
+
+```
+spawn_count = 0
+prompt = "<RUN_DIR + task + chosen_ref_id>. Phase 1부터 시작."
+
+while spawn_count < 12 (safety cap):
+  result = Agent({
+    subagent_type: "omd-master",
+    description: "Run design harness round N",
+    prompt: prompt
+  })
+  spawn_count += 1
+
+  handoff_path = "<RUN_DIR>/.handoff.json"
+  if not exists(handoff_path):
+    relay result text to user; halt
+
+  handoff = JSON.parse(Read(handoff_path))
+
+  if handoff.user_prose:
+    print handoff.user_prose to user
+
+  if handoff.status == "done": halt
+  if handoff.status == "error": halt + show
+  if handoff.status == "ask_user":
+    questions = JSON.parse(Read(handoff.questions_file))
+    answers = AskUserQuestion({ questions: questions.questions })
+    answers_file = "<RUN_DIR>/checkpoints/<handoff.checkpoint_id>.answers.json"
+    Write(answers_file, JSON.stringify({checkpoint_id, answers}))
+    prompt = "continue checkpoint:" + handoff.checkpoint_id + " — answers at " + answers_file
+```
+
+### Safety cap
+
+한 번의 `/omd-harness` 호출에 최대 12 spawn. 초과 시 사용자에게 escalate ("master가 12 spawn 초과, 멈춥니다 — run dir 보존").
+
+### 재진입
+
+사용자가 자연어로 "go" / "fix X" 답하면 동일 loop 재시작. master는 `.handoff.json` 보고 어디까지 갔는지 파악.
+
+## 사용자 체크포인트 처리
+
+Master가 체크포인트에서 turn을 종료한 후 다음 사용자 메시지가:
+
+- **하네스 컨텍스트 안의 응답** (예: "go", "fix the home screen IA", "stop") → master 재spawn + 그대로 전달
+- **다른 작업으로 바뀐 메시지** → run 디렉토리에 `paused.flag` 생성. 나중에 `/omd-harness resume` 하면 재개
+
+## 산출물 위치 (master가 emit, 이 스킬은 안내만)
+
+```
+.omd/runs/run-<ts>-<slug>/
+├── task.md
+├── brief.md
+├── references-cited.md
+├── journey.mmd
+├── wireframes/
+├── DESIGN.md.patch
+├── components/
+│   ├── manifest.json
+│   └── microcopy.json
+├── assets/
+│   ├── brief.md
+│   ├── manifest.json
+│   ├── briefs/
+│   ├── fallback/
+│   └── pinterest-refs/
+├── eval/
+│   ├── deterministic.json
+│   ├── jury.json
+│   └── screenshots/
+├── persona-feedback/
+│   └── <persona>.json
+├── critique.md
+├── handoff/
+│   ├── v0.zip
+│   ├── cursor.zip
+│   └── subframe.zip
+├── run.log
+└── postmortem.md
+```
+
+## 이 스킬이 하지 않는 것
+
+- Phase 로직 실행 (master)
+- Sub-agent 직접 spawn (master)
+- 사용자 응답 해석/라우팅 (master)
+- DESIGN.md 직접 수정 (Phase 5에서 master)
+
+## 금지
+
+- Master 없이 phase를 직접 수행하지 말 것
+- 사용자 체크포인트를 자동 승인하지 말 것
+- Run 디렉토리를 임의로 정리/삭제하지 말 것
+- Step 2.3 verify gate 통과 전에 master spawn 절대 금지

package/skills/omd-init/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: omd:init
-description: "프로젝트 루트에 DESIGN.md를 생성합니다. 사용자가 프로젝트를 묘사하면 67개 레퍼런스 중 가장 잘 맞는 것을 추천하고, 사용자가 고른 레퍼런스의 톤&매너를 preserve하면서 프로젝트 맥락 delta만 반영한 variation을 생성합니다. '디자인 시스템 만들어줘', 'DESIGN.md 세팅', 'brand 초기화', 'omd init' 같은 요청에 트리거됩니다. CLAUDE.md / AGENTS.md / Cursor rule shim도 함께 설치."
+description: "프로젝트 루트에 DESIGN.md를 부트스트랩 — 67개 실제 기업 레퍼런스 중 컨텍스트 매칭으로 추천하고 선택된 레퍼런스의 톤&매너를 보존한 variation을 생성. DESIGN.md 부재 상태에서의 UI 작업 또는 '디자인 시스템 세팅', 'set up our design system', 「デザインシステムを作って」, 「建立設計系統」류의 요청에 트리거. CLAUDE.md / AGENTS.md / Cursor rule shim도 함께 설치."
 ---
 
 # omd:init — DESIGN.md Bootstrap