oh-my-design-cli 0.1.3 → 1.0.1

package/.claude/hooks/post-edit-watch.cjs

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+// PostToolUse hook — runs after Edit/Write on .tsx/.jsx/.css/.scss files.
+// Detects if the change introduced a hex/spacing value that's NOT in
+// DESIGN.md tokens, and surfaces a one-line suggestion to capture as preference.
+//
+// Hook input shape (Claude Code hook contract):
+//   stdin = JSON with toolName / args / etc.
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+const designMd = path.join(projectDir, 'DESIGN.md');
+
+let input = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', (c) => (input += c));
+process.stdin.on('end', () => {
+  let payload = {};
+  try {
+    payload = JSON.parse(input || '{}');
+  } catch {
+    process.exit(0);
+  }
+  const toolName = payload.toolName || payload.tool_name || '';
+  if (!['Edit', 'Write', 'MultiEdit'].includes(toolName)) {
+    process.exit(0);
+  }
+  const filePath = payload.toolInput?.file_path || payload.toolInput?.filePath || '';
+  if (!/\.(tsx|jsx|ts|js|css|scss)$/i.test(filePath)) {
+    process.exit(0);
+  }
+
+  const newText =
+    payload.toolInput?.content ||
+    payload.toolInput?.new_string ||
+    '';
+  if (!newText) process.exit(0);
+
+  // Normalize a hex to canonical 6-char lowercase form (#abc → #aabbcc)
+  function normHex(h) {
+    let s = h.toLowerCase();
+    if (s.length === 4) {
+      // #abc → #aabbcc
+      s = '#' + s[1] + s[1] + s[2] + s[2] + s[3] + s[3];
+    } else if (s.length === 9) {
+      // #aarrggbb (8-char includes alpha) — strip alpha for comparison
+      s = s.slice(0, 7);
+    }
+    return s;
+  }
+
+  // Extract hexes from new content
+  const rawHexes = newText.match(/#[0-9a-f]{3,8}\b/gi) || [];
+  const hexes = [...new Set(rawHexes.map(normHex))];
+  if (hexes.length === 0) process.exit(0);
+
+  // Read DESIGN.md hexes — also handle CSS vars and oklch (Tailwind v4) by
+  // signaling N/A when DESIGN.md is purely token-driven (no inline hex).
+  let designHexes = new Set();
+  let designUsesTokenSystem = false;
+  if (fs.existsSync(designMd)) {
+    try {
+      const text = fs.readFileSync(designMd, 'utf8');
+      const lower = text.toLowerCase();
+      for (const h of (lower.match(/#[0-9a-f]{3,8}\b/g) || [])) {
+        designHexes.add(normHex(h));
+      }
+      // If DESIGN.md mostly uses oklch() / CSS vars / token names, hex-only
+      // comparison is unreliable — skip warning to avoid noise.
+      const hexCount = designHexes.size;
+      const oklchCount = (lower.match(/oklch\(/g) || []).length;
+      const cssVarCount = (lower.match(/var\(--/g) || []).length;
+      if ((oklchCount + cssVarCount) > hexCount * 2) {
+        designUsesTokenSystem = true;
+      }
+    } catch {
+      // ignore
+    }
+  }
+
+  if (designUsesTokenSystem) process.exit(0); // skip — too noisy
+  const introduced = hexes.filter((h) => !designHexes.has(h));
+  if (introduced.length === 0) process.exit(0);
+
+  const lines = [
+    '',
+    'OMD WATCH:',
+    `방금 ${path.basename(filePath)} 에 DESIGN.md에 없는 색이 들어갔어요: ${introduced.slice(0, 3).join(', ')}`,
+    '의도된 거면 \`omd remember "<설명>" --context "' + filePath + '"\` 으로 preference 캡처 추천.',
+    '',
+  ];
+
+  // Hook contract: write to additionalContext via JSON stdout
+  process.stdout.write(JSON.stringify({ additionalContext: lines.join('\n') }));
+});
+

package/.claude/hooks/session-end-foldin.cjs

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+// Stop hook — at session end, run fold-in algorithm on .omd/preferences.md.
+// If proposals exceed threshold, append a note to .omd/timeline.md so the
+// next SessionStart hook surfaces it as "fold-in proposals ready: N".
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+const preferencesMd = path.join(projectDir, '.omd', 'preferences.md');
+const timelineMd = path.join(projectDir, '.omd', 'timeline.md');
+const configJson = path.join(projectDir, '.omd', 'config.json');
+
+if (!fs.existsSync(preferencesMd)) process.exit(0);
+
+let config = {
+  fold_in_score_threshold: 60,
+  recurrence_window_days: 7,
+};
+try {
+  if (fs.existsSync(configJson)) {
+    config = { ...config, ...JSON.parse(fs.readFileSync(configJson, 'utf8')) };
+  }
+} catch {
+  // ignore
+}
+
+let prefText;
+try {
+  prefText = fs.readFileSync(preferencesMd, 'utf8');
+} catch {
+  process.exit(0);
+}
+
+// Parse pending entries (very rough)
+const blocks = prefText.split(/^### /m).slice(1);
+const now = Date.now();
+const windowMs = config.recurrence_window_days * 24 * 3600 * 1000;
+const byScope = new Map();
+
+for (const block of blocks) {
+  const tsMatch = /^- ts:\s*(.+)$/m.exec(block);
+  const scopeMatch = /^- scope:\s*(.+)$/m.exec(block);
+  const statusMatch = /^- status:\s*(\w+)$/m.exec(block);
+  const importanceMatch = /^- importance:\s*([1-5])$/m.exec(block);
+  if ((statusMatch?.[1] || 'pending') !== 'pending') continue;
+  if (!tsMatch || !scopeMatch) continue;
+  const ts = new Date(tsMatch[1]).getTime();
+  if (Number.isNaN(ts) || now - ts > windowMs) continue;
+  const scope = scopeMatch[1];
+  const importance = parseInt(importanceMatch?.[1] || '3', 10);
+  const list = byScope.get(scope) || [];
+  list.push({ ts, importance });
+  byScope.set(scope, list);
+}
+
+const proposals = [];
+for (const [scope, entries] of byScope.entries()) {
+  if (entries.length < 3) continue;
+  const importanceAvg = entries.reduce((s, e) => s + e.importance, 0) / entries.length;
+  // Hard floor matches src/core/memory.ts — keep these in sync.
+  if (importanceAvg < 2.5) continue;
+  const lastTs = entries.reduce((m, e) => Math.max(m, e.ts), 0);
+  const daysSince = (now - lastTs) / (24 * 3600 * 1000);
+  const recency = Math.exp(-daysSince / 7);
+  const score = entries.length * importanceAvg * recency * 10;
+  if (score >= config.fold_in_score_threshold) {
+    proposals.push({ scope, count: entries.length, score: Math.round(score) });
+  }
+}
+
+if (proposals.length === 0) process.exit(0);
+
+// Append to timeline.md
+const ts = new Date().toISOString();
+const block =
+  `## ${ts} — fold_in_proposal\n\n` +
+  `${proposals.length} fold-in proposals ready (top: ${proposals[0].scope}, score ${proposals[0].score}).\n\n` +
+  '```json\n' +
+  JSON.stringify(proposals.slice(0, 5), null, 2) +
+  '\n```\n\n';
+
+if (!fs.existsSync(path.dirname(timelineMd))) {
+  fs.mkdirSync(path.dirname(timelineMd), { recursive: true });
+}
+if (!fs.existsSync(timelineMd)) {
+  fs.writeFileSync(timelineMd, '# OMD TIMELINE — per-session journal\n\n' + block);
+} else {
+  fs.appendFileSync(timelineMd, block);
+}
+
+// Optional: print one-line confirmation to stdout
+process.stdout.write(JSON.stringify({}) || '');
+

package/.claude/hooks/session-state-loader.cjs

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+// SessionStart hook — load .omd/state.md (and a recent timeline tail) into the
+// session as additionalContext. If state.md is missing or stale, recompute
+// best-effort from preferences.md + timeline.md.
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+const stateMd = path.join(projectDir, '.omd', 'state.md');
+const timelineMd = path.join(projectDir, '.omd', 'timeline.md');
+const preferencesMd = path.join(projectDir, '.omd', 'preferences.md');
+
+function safeRead(p) {
+  try {
+    return fs.readFileSync(p, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+const lines = [];
+
+if (fs.existsSync(stateMd)) {
+  const content = safeRead(stateMd);
+  if (content) {
+    lines.push('## OMD ENVIRONMENT STATE');
+    lines.push('');
+    lines.push(content.split('\n').slice(0, 60).join('\n')); // cap injection size
+    lines.push('');
+  }
+} else if (fs.existsSync(preferencesMd)) {
+  // Best-effort fallback — count pending entries
+  const text = safeRead(preferencesMd) || '';
+  const pendingCount = (text.match(/^- status:\s*pending\b/gm) || []).length;
+  if (pendingCount > 0) {
+    lines.push('## OMD ENVIRONMENT STATE');
+    lines.push('');
+    lines.push(`Pending preferences: ${pendingCount}${pendingCount >= 7 ? ' — consider /omd-learn review' : ''}`);
+    lines.push('');
+  }
+}
+
+if (fs.existsSync(timelineMd)) {
+  const text = safeRead(timelineMd) || '';
+  const blocks = text.split(/^## /m).slice(1).slice(-3);
+  if (blocks.length > 0) {
+    lines.push('## RECENT TIMELINE (last 3)');
+    lines.push('');
+    for (const b of blocks) {
+      const firstLine = b.split('\n')[0];
+      const summary = (b.split('\n').slice(2).find((l) => l.trim()) || '').trim();
+      lines.push(`- ${firstLine.trim()} — ${summary}`);
+    }
+    lines.push('');
+  }
+}
+
+if (lines.length > 0) {
+  process.stdout.write(JSON.stringify({ additionalContext: lines.join('\n') }));
+}
+

package/.claude/hooks/skill-activation.cjs

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+// UserPromptSubmit hook — DESIGN.md existence gate.
+//
+// Scope (2026-05-07, simplified from the prior keyword/regex forced-eval
+// system): the hook now does the one thing description-based skill
+// triggering cannot do — file-system state checks. If the project has no
+// DESIGN.md and the user is asking for UI/design work, we surface a
+// single warning recommending omd:init first. Everything else (which
+// skill to invoke, when, in what language) is handled by Claude reading
+// each SKILL.md description, the standard Anthropic mechanism.
+//
+// What was removed:
+//   - .claude/skills/skill-rules.json (per-skill keyword/regex pools)
+//   - the "OMD SKILL ACTIVATION CHECK" forced-injection block
+//   - per-skill required/suggested classification
+// All those overlapped with SKILL.md descriptions and created a
+// dual-source-of-truth maintenance burden.
+//
+// What remains:
+//   - DESIGN.md existence check
+//   - a small inline UI-cue keyword set (KO/EN/JA/ZH-TW) so we only fire
+//     the warning when the prompt is actually about UI — otherwise a
+//     casual "what's 2+2" wouldn't get spammed with init reminders
+//
+// Plain CommonJS so it works on any Node ≥18 without build deps.
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+
+// Inline UI cue list (gate scope only). Tiny on purpose — this is a
+// "is the user asking for UI work?" sniff test, not a full taxonomy.
+// If you find yourself wanting to add 50 entries here, that's a sign
+// the description on the relevant SKILL.md should grow instead.
+const UI_CUES = [
+  // Korean
+  '디자인', '레이아웃', '화면', '컴포넌트', '버튼', '카드', '색', '색상',
+  '폰트', '스타일', '브랜드', '리팩토링', '랜딩', '페이지',
+  // English
+  'design', 'layout', 'component', 'button', 'card', 'color', 'colour',
+  'font', 'style', 'brand', 'refactor', 'landing', 'redesign', 'rework',
+  // Japanese
+  'デザイン', 'レイアウト', 'コンポーネント', 'ボタン', 'スタイル',
+  'カラー', 'フォント', 'ブランド', 'ランディング',
+  // Traditional Chinese
+  '設計', '佈局', '元件', '按鈕', '風格', '顏色', '字體', '品牌', '落地頁',
+];
+
+let prompt = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', (chunk) => (prompt += chunk));
+process.stdin.on('end', () => {
+  const designMdPath = path.join(projectDir, 'DESIGN.md');
+  if (fs.existsSync(designMdPath)) process.exit(0);
+
+  const lower = prompt.toLowerCase();
+  const looksLikeUiWork = UI_CUES.some(
+    (k) => lower.includes(k.toLowerCase()) || prompt.includes(k),
+  );
+  if (!looksLikeUiWork) process.exit(0);
+
+  const lines = [
+    '',
+    'OMD GATE',
+    '⚠️  DESIGN.md not found at project root.',
+    '   This prompt looks like UI / design work. Run the omd:init skill first',
+    '   to bootstrap DESIGN.md, then re-issue the request so it can be applied',
+    '   with brand context.',
+    '',
+  ];
+  process.stdout.write(JSON.stringify({ additionalContext: lines.join('\n') }));
+});

package/.claude/settings.json

@@ -0,0 +1,55 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "_doc": "OmD project hooks — auto-installed by `omd install-skills`. Re-run with --force to refresh.",
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PROJECT_DIR}/.claude/hooks/skill-activation.cjs",
+            "timeout": 3000
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PROJECT_DIR}/.claude/hooks/session-state-loader.cjs",
+            "timeout": 3000
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PROJECT_DIR}/.claude/hooks/post-edit-watch.cjs",
+            "timeout": 2000
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PROJECT_DIR}/.claude/hooks/session-end-foldin.cjs",
+            "timeout": 5000
+          }
+        ]
+      }
+    ]
+  }
+}
+

package/AGENTS.md

@@ -0,0 +1,111 @@
+# 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).
+- `references/` — 67 real-company DESIGN.md files used as bundled references.
+- `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).
+- `spec/omd-v0.1.md` — OmD spec (15-section DESIGN.md format).
+- `research/harness-design/` — Design harness research + integration design.
+- `skills/omd-lab-02-design-harness/` — Lab #02 versioned harness experiments.
+
+## 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 `.codex/skills/omd-harness/` (or `.claude/skills/omd-harness/` for 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 internally bootstraps the run dir via a hidden `omd harness` helper (slug consistency, standardized subdirs, INDEX.md append). This helper is NOT a user surface — always use `/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 / DESIGN.md.patch (master + omd init prepare) → **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`, 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.
+
+## Hard rules (apply across channels)
+
+- Never fabricate DESIGN.md §11-13 (Brand Narrative / Principles / Personas) facts. Use `[FILL IN]` placeholders if user-provided facts are absent.
+- Never introduce a token absent from DESIGN.md without going through Phase 5 (system extension with checkpoint #2 approval).
+- 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.
+
+## 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 -->
+

package/README.ja.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="logo-bg.png" width="480" alt="oh-my-design" />
+  <img src=".github/assets/logo-bg.png" width="480" alt="oh-my-design" />
 </p>
 
 <h1 align="center">oh-my-design</h1>

package/README.ko.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="logo-bg.png" width="480" alt="oh-my-design" />
+  <img src=".github/assets/logo-bg.png" width="480" alt="oh-my-design" />
 </p>
 
 <h1 align="center">oh-my-design</h1>